@inkobytes/nexus 1.0.7 → 1.0.8

package/src/commands/doctor.js

@@ -10,39 +10,19 @@ import { listLocks } from '../lib/lockManager.js';
 import { getConfig } from '../lib/config.js';
 import { AGENT_SCOPE_LIST } from '../lib/agentScopes.js';
 import { DEFAULT_MATRIX, loadPermissions, getChmodPath } from '../lib/permissions.js';
-
-const MONTH_NAMES = [
-  'January',
-  'February',
-  'March',
-  'April',
-  'May',
-  'June',
-  'July',
-  'August',
-  'September',
-  'October',
-  'November',
-  'December',
-];
-
-const START_MARKER = '<!-- NEXUS-AGENT-PROTOCOL:START -->';
-const END_MARKER = '<!-- NEXUS-AGENT-PROTOCOL:END -->';
-
-const CONTINUITY_TEMPLATE = `# CONTINUITY
-Goal: Project setup
-State: Planning
-
-Now: Initial Nexus setup
-Next: Confirm first task
-Blockers: None
-Decisions:
-- Nexus manages swarm coordination
-- Continuity and memories are agent-local
-Files:
-- _NEXUS_QUEUE.md
-- _NEXUS_STANDUP.md
-`;
+import {
+  CONTINUITY_TEMPLATE,
+  END_MARKER,
+  MEMORY_INDEX_GUARDRAIL,
+  MEMORY_INDEX_TEMPLATE,
+  REQUIRED_CONTEXT_READ,
+  SKILL_CONTEXT_GUARDRAIL,
+  START_MARKER,
+  currentMemoryMonthFolder,
+  fullEntrypoint,
+  protocolBlock,
+} from '../lib/protocolText.js';
+import { HOOK_AGENT_CONFIGS, hookStatus } from './hooks.js';
 
 const LOCAL_DECISIONS_TEMPLATE = `# Decisions
 
@@ -53,148 +33,6 @@ const LOCAL_GITIGNORE_LINES = ['DECISIONS.md', 'docs-priv/', '.nexus/presence/']
 const STANDUP_FORMAT_GUIDANCE = 'YYYY-MM-DD HH:MM AM/PM @agent [STATUS]: message';
 const STANDUP_RULES_LINE = `*Rules: Append new entries at the bottom. One line per message. Use \`${STANDUP_FORMAT_GUIDANCE}\` so relevance is visible. Use 🧵 for long discussions.*`;
 
-const MEMORY_INDEX_TEMPLATE = `# Memory Index
-
-Newest first, max 10 visible entries.
-
-Format:
-
-- YYYY-Month/YYYY-MM-DD-HHMM-topic.md - short session label
-
-Entries live in month folders from the start, for example:
-
-- \`2026-January/2026-01-15-1030-project-setup.md\`
-- \`2026-February/2026-02-01-0900-debug-session.md\`
-
-This keeps monthly review simple: ask an agent to read one month folder and summarize the Markdown files.
-
-`;
-
-function currentMemoryMonthFolder(now = new Date()) {
-  return `${now.getFullYear()}-${MONTH_NAMES[now.getMonth()]}`;
-}
-
-function protocolBlock(agent) {
-  return `${START_MARKER}
-
-## Nexus Project Protocol
-
-This project uses Nexus for multi-agent coordination.
-
-### Start Here
-
-1. Read \`_NEXUS_CONSTITUTION.md\`.
-2. Read \`_NEXUS_QUEUE.md\` for executable priorities.
-3. Read \`_NEXUS_STANDUP.md\` for comms, decisions, and completion notes.
-4. Read \`USER.md\` if present for local human preferences.
-5. Read \`${agent.continuity}\` for current session state.
-6. Read \`${agent.memoryIndex}\` and the latest memory entry when resync is needed.
-
-### Nexus Rules
-
-- Claim before editing shared project files: \`nexus claim <path> @Agent "intent"\`.
-- Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics.
-- Release each claimed file as soon as it reaches a coherent checkpoint.
-- Never hold claims just to bundle a prettier feature commit; that blocks other agents.
-- Release finished work through Nexus: \`nexus release <path> "commit message"\`.
-- Use \`nexus next @Agent\` for the next safe queue task.
-- Do not free-roam into unassigned or \`Auto-flow: no\` work without user approval.
-- Direct user instruction can override queue order, but not claim/release, data, security, or approval gates.
-- If no safe task remains, announce \`Standby\` with what you are waiting for, then stop until user input, queue change, or explicit assignment.
-
-### Current File State
-
-- Treat previous chat context, cached model memory, and earlier reads as stale when file contents matter.
-- Before claiming what a file says, making edits, or judging current state, read the file from disk with a fresh command.
-- Treat \`nexus claim\` as the atomic lock-and-read boundary and its output as fresh file state for the claimed path.
-- If you read a shared file before claiming it, treat that read as stale after claim succeeds.
-- If another agent or tool may have touched the file since your last read, re-read it before editing.
-- If a claim appears stale, do not edit through it; run \`nexus status\` or \`nexus doctor\`, then clean only when ownership is clearly abandoned.
-
-### Drills
-
-Drill guidance is defined in \`_NEXUS_CONSTITUTION.md\`.
-If the situation resembles a drill, use that drill before acting.
-
-### Delegated Work
-
-- Lead agents own the repo effects of their subagents, tools, and parallel workers.
-- Claim the full path scope before delegating shared-file work.
-- Give subagents the claimed path, intent, non-goals, and boundaries.
-- Re-read affected files after subagent work before final edits, release, or current-state claims.
-- Mention delegated work in release or \`nexus standup\` notes when it affected files, tests, or risk.
-
-### Git Write Safety
-
-- Before git writes, verify \`pwd\`, repo root, branch/status, and remotes.
-- Stop if they do not match the requested project.
-- Never infer from similar folder names or cached context.
-- Require explicit confirmation before push/force-push, main/master, remote changes, or deletes.
-- To remove private agent files from git, untrack them; do not delete local folders.
-- Agent instruction files are shared protocol files; normal edits require claim/release, while \`nexus doctor --fix\` may update managed protocol blocks after user approval.
-- Agents work inside assigned work zones. If a change crosses work-zone boundaries or alters a shared contract another zone may depend on, announce it in \`_NEXUS_STANDUP.md\` before release and ask if coordination is needed.
-
-### Supply-Chain Safety
-
-- Do not install third-party packages that have existed for less than 14 days.
-- Before adding a new dependency, verify the package creation date and the specific version publish date.
-- If the package or version is younger than 14 days, or either date cannot be verified, stop and ask the user.
-- Run \`nexus doctor\` before installs; review any Security findings before running package scripts.
-- \`nexus doctor\` is cheap, local, and idempotent.
-- If \`nexus doctor\` reports Security, Package Privacy, Git Privacy, or supply-chain findings, stop and report before fixing or installing.
-- Treat install hooks and scripts with network commands, webhooks, raw sockets, SSH, or secret-looking variables as human-review only.
-- Prefer built-in runtime APIs and existing project dependencies when they fit.
-
-### Agent-Local Files
-
-\`${agent.continuity}\` and \`${agent.memoryIndex}\` are agent-local handoff files.
-They are exempt from Nexus claim/release unless the user says otherwise.
-
-### Memory Flow
-
-- On session start, read \`${agent.memoryIndex}\`.
-- If the index has entries, read the newest \`${agent.memoryDir}/YYYY-Month/YYYY-MM-DD-HHMM-topic.md\` entry.
-- Durable architecture and protocol decisions belong in \`DECISIONS.md\`; mention them in \`_NEXUS_STANDUP.md\` only when active agents need to coordinate around them.
-- Memory entries are session handoffs.
-- When writing your own memory entry, create the current month folder under \`${agent.memoryDir}\` if it is missing.
-- Do not create or repair other agents' memory folders manually; use \`nexus doctor --fix\` for broad scaffold repair.
-- On session end, pause, or checkpoint request:
-  1. Run \`nexus checkout @${agent.aliases[0]}\` to clear your presence heartbeat.
-  2. Create one new memory file: \`${agent.memoryDir}/YYYY-Month/YYYY-MM-DD-HHMM-topic.md\`.
-- Add the newest file to the top of \`${agent.memoryIndex}\`.
-- Keep the index to the 10 newest visible entries.
-- For monthly review, read one month folder such as \`${agent.memoryDir}/2026-January/\` and summarize the Markdown files.
-
-Memory entry format:
-
-\`\`\`markdown
-# YYYY-MM-DD-HHMM - <topic>
-
-## Session Summary
-- What we worked on: [<=50 words]
-- What got done: [bullet list, max 5]
-- Where we stopped: [exact state, <=30 words]
-
-## Next Session Needs
-- Immediate next task: [<=20 words]
-- Blockers: [None, or list]
-- Open questions: [if any]
-
-## Context to Carry
-- Key decisions made: [max 3 bullets]
-- Files touched: [max 5 paths]
-- Gotchas/warnings: [anything next session should watch for]
-\`\`\`
-
-${END_MARKER}
-`;
-}
-
-function fullEntrypoint(agent) {
-  return `# ${agent.label} Agent Guide
-
-${protocolBlock(agent)}`;
-}
 
 function upsertProtocolBlock(content, block) {
   const cleanContent = removeUnmanagedProtocolBlock(content);
@@ -347,6 +185,7 @@ function repairStandupGuidance(content) {
 export default function doctor(args) {
   const fix = args.includes('--fix');
   const json = args.includes('--json');
+  const checkHooks = args.includes('--hooks');
   const root = cwd();
   const colors = createColors();
   const sections = {
@@ -361,6 +200,7 @@ export default function doctor(args) {
     Memories: [],
     Locks: [],
     'Generated Artifacts': [],
+    Hooks: [],
     promptCHMOD: [],
     'Queue Authorship': [],
   };
@@ -423,6 +263,26 @@ export default function doctor(args) {
     sections['Generated Artifacts'].push(issue);
   }
 
+  if (checkHooks) {
+    for (const agent of Object.keys(HOOK_AGENT_CONFIGS)) {
+      const status = hookStatus(agent);
+      if (status.status === 'current') {
+        sections.Hooks.push({
+          issue: `${agent} Nexus hook is installed`,
+          fix: 'No action needed.',
+          ok: true,
+        });
+        continue;
+      }
+
+      const fixHint = `Run \`nexus hooks install --agent ${agent}\`${status.status === 'foreign' ? ' after reviewing the existing hook, or add `--force` to replace it' : ''}.`;
+      sections.Hooks.push({
+        issue: `${agent} Nexus hook is ${status.status} at ${status.path}`,
+        fix: fixHint,
+      });
+    }
+  }
+
   if (!ensureFile(join(root, 'DECISIONS.md'), LOCAL_DECISIONS_TEMPLATE, fix, changes)) {
     sections['Nexus Files'].push({
       issue: 'Missing local DECISIONS.md',
@@ -992,7 +852,7 @@ function isNexusProductRepo(root) {
 }
 
 function repairReadmeProtocolDoc(content) {
-  return content
+  let next = content
     .replace(
       [
         '- [ ] TASK/Codex: Add doctor stale-lock category',
@@ -1021,10 +881,6 @@ function repairReadmeProtocolDoc(content) {
         '  - Notes: Add a doctor section for stale locks with tests and clear fix guidance.',
       ].join('\n'),
     )
-    .replace(
-      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
-      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it. Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.',
-    )
     .replace(
       [
         '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
@@ -1039,25 +895,39 @@ function repairReadmeProtocolDoc(content) {
         '1. Run `nexus start` when entering an existing repo; it does not replace claim/release.',
         '2. Read `_NEXUS_CONSTITUTION.md`.',
         '3. Read `USER.md` when present.',
-        '4. Read continuity and latest memory when present.',
+        `4. ${REQUIRED_CONTEXT_READ}`,
         '5. Read `_NEXUS_QUEUE.md` before taking follow-on work.',
         '6. Claim before touching shared project files.',
         '7. Release each claimed tracked file as soon as it reaches a coherent checkpoint.',
         '8. Use `nexus next @Agent` instead of free-roaming.',
       ].join('\n'),
     )
-    .replace(
-      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
-      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\nNexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.',
-    )
     .replace(
       'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> release`.',
       'The CLI is the coordination engine. The skill is the lean playbook for this flow: `start -> claim -> work -> release -> next`.',
     );
+
+  const queueReviewReadme = 'Auto-flow work in `Ready Queue` should also include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.';
+  if (!next.includes(queueReviewReadme)) {
+    next = next.replace(
+      'Keep items dashboard-friendly: include `Id`, `Epic`, `Status`, `Depends on`, `Files`, `Affinity`, `Cost`, `Auto-flow`, and `Notes`. Use `Files` to expose conflict surfaces, `Depends on` for hard blockers, and `Auto-flow: no` when a task needs planning or human approval before an agent grabs it.',
+      `Keep items dashboard-friendly: include \`Id\`, \`Epic\`, \`Status\`, \`Depends on\`, \`Files\`, \`Affinity\`, \`Cost\`, \`Auto-flow\`, and \`Notes\`. Use \`Files\` to expose conflict surfaces, \`Depends on\` for hard blockers, and \`Auto-flow: no\` when a task needs planning or human approval before an agent grabs it. ${queueReviewReadme}`,
+    );
+  }
+
+  const agentNativeReadme = 'Nexus is agent-native and file-native, not human-native: optimize for concurrency and rollback, not feature-commit aesthetics. Do not hold claims to bundle related work into prettier feature commits; that blocks other agents waiting on files.';
+  if (!next.includes(agentNativeReadme)) {
+    next = next.replace(
+      'Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.',
+      `Agent-local continuity and memory files are exempt from claim/release unless the human says otherwise.\n\n${agentNativeReadme}`,
+    );
+  }
+
+  return next;
 }
 
 function repairNexusSkillDoc(content) {
-  return content
+  let next = content
     .replace(
       [
         '1. Run `nexus start`; set `NEXUS_AGENT` for your CLI, or pass `--agent @agy|@claude|@codex|@gemini`. Start is orientation only, not permission to edit.',
@@ -1085,13 +955,14 @@ function repairNexusSkillDoc(content) {
       ].join('\n'),
       [
         '8. Treat claim output as current file state. Ignore cached file memory when contents matter.',
-        '9. Work only inside the claimed surface and run focused validation.',
-        '10. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
+        '9. If a hook blocks access because a path is unclaimed, stop and claim that exact path. Do not work around the hook with another command, cached content, or manual git operation.',
+        '10. Work only inside the claimed surface and run focused validation.',
+        '11. Release each claimed tracked file through Nexus as soon as it reaches a coherent checkpoint:',
       ].join('\n'),
     )
     .replace(
       '```\\n\\n## Queue Items',
-      '```\\n\\n11. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
+      '```\\n\\n12. Do not hold claims to bundle related work into a prettier feature commit. Nexus is agent-native and file-native: optimize for file availability, rollback safety, and agent throughput.\\n\\n## Queue Items',
     )
     .replace(
       [
@@ -1111,6 +982,25 @@ function repairNexusSkillDoc(content) {
       '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
       '- `Auto-flow: yes` means an agent can grab it after `nexus next`; use `no` when planning or human approval is needed.\n- Auto-flow work in `Ready Queue` should include `Review: approved` and `Approved by: human`, or `doctor` will flag it and `nexus next` may skip it.\n- `Notes` should carry dashboard-useful context, not a whole design doc.',
     );
+
+  if (!next.includes('Continuity is the compaction-safe session ledger; latest memory is required startup/resume context.')) {
+    next = next.replace(
+      '- Agent-local continuity and memory files are claim-exempt unless the user says otherwise.',
+      `- Agent-local continuity and memory files are claim-exempt unless the user says otherwise.\n- ${SKILL_CONTEXT_GUARDRAIL}\n- ${MEMORY_INDEX_GUARDRAIL}`,
+    );
+  }
+
+  const mandatoryNote = 'If the user, repo, or hook says Nexus is active, treat this skill as mandatory workflow. It is not optional advice.';
+  if (!next.includes(mandatoryNote)) {
+    next = next.replace('## Loop', `${mandatoryNote}\n\n## Loop`);
+  }
+
+  next = next.replace(
+    '4. Read continuity and latest memory when present.',
+    `4. ${REQUIRED_CONTEXT_READ}`,
+  );
+
+  return next;
 }
 
 const SUSPICIOUS_SCRIPT_PATTERNS = [

package/src/commands/hooks.js

@@ -0,0 +1,305 @@
+/**
+ * nexus hooks - install agent-specific local guard hooks
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { homedir } from 'os';
+
+export const HOOK_AGENT_CONFIGS = {
+  '@codex': {
+    label: 'Codex',
+    defaultTarget: '~/.codex/hooks/pre_tool_use_guard.py',
+  },
+  '@claude': {
+    label: 'Claude',
+    defaultTarget: '~/.claude/hooks/nexus_pre_tool_use_guard.py',
+  },
+  '@gemini': {
+    label: 'Gemini',
+    defaultTarget: '~/.gemini/hooks/nexus_pre_tool_use_guard.py',
+  },
+};
+
+export const HOOK_FINGERPRINT = 'NEXUS_HOOK_TEMPLATE_V1';
+
+const COMMAND_USAGE = 'Usage: nexus hooks install --agent @codex|@claude|@gemini|all [--target <path>] [--force]';
+
+function parseArgs(args) {
+  if (args[0] !== 'install') throw new Error(COMMAND_USAGE);
+
+  let agent = '';
+  let target = '';
+  let force = false;
+
+  for (let index = 1; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--force') {
+      force = true;
+      continue;
+    }
+
+    if (arg === '--agent') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(COMMAND_USAGE);
+      agent = value;
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--target') {
+      const value = args[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(COMMAND_USAGE);
+      target = value;
+      index += 1;
+      continue;
+    }
+
+    throw new Error(COMMAND_USAGE);
+  }
+
+  const normalizedAgent = agent === '@all' ? 'all' : agent;
+  if (normalizedAgent === 'all' && target) throw new Error('Usage: nexus hooks install --agent all [--force]');
+  if (normalizedAgent !== 'all' && !HOOK_AGENT_CONFIGS[normalizedAgent]) throw new Error(COMMAND_USAGE);
+  return {
+    agent: normalizedAgent,
+    target: normalizedAgent === 'all' ? '' : target || HOOK_AGENT_CONFIGS[normalizedAgent].defaultTarget,
+    force,
+  };
+}
+
+export function expandHome(path) {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return resolve(homedir(), path.slice(2));
+  return resolve(path);
+}
+
+export function hookStatus(agent, target = HOOK_AGENT_CONFIGS[agent]?.defaultTarget) {
+  if (!HOOK_AGENT_CONFIGS[agent]) throw new Error(`Unsupported hook agent: ${agent}`);
+  const path = expandHome(target);
+  if (!existsSync(path)) return { agent, path, status: 'missing' };
+
+  const content = readFileSync(path, 'utf-8');
+  if (!content.includes(HOOK_FINGERPRINT)) return { agent, path, status: 'foreign' };
+  if (!content.includes(`NEXUS_AGENT = '${agent}'`)) return { agent, path, status: 'wrong-agent' };
+  return { agent, path, status: 'current' };
+}
+
+export function hookScriptContent(agent) {
+  if (!HOOK_AGENT_CONFIGS[agent]) throw new Error(`Unsupported hook agent: ${agent}`);
+
+  return `#!/usr/bin/env python3
+"""Nexus PreToolUse guard.
+
+${HOOK_FINGERPRINT}
+Blocks writes to Nexus repo files until the exact path is claimed.
+"""
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+NEXUS_AGENT = '${agent}'
+ALLOW_WITHOUT_CLAIM = {
+    '_NEXUS.md',
+    '.codex/CONTINUITY.md',
+    '.claude/CONTINUITY.md',
+    '.gemini/CONTINUITY.md',
+}
+ALLOW_PREFIXES = (
+    '.nexus/',
+    '.codex/memories/',
+    '.claude/memories/',
+    '.gemini/memories/',
+)
+
+
+def load_payload() -> dict:
+    try:
+        raw = sys.stdin.read()
+        return json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return {}
+
+
+def block(reason: str) -> None:
+    print(json.dumps({
+        'hookSpecificOutput': {
+            'hookEventName': 'PreToolUse',
+            'permissionDecision': 'deny',
+            'permissionDecisionReason': reason,
+        }
+    }))
+    raise SystemExit(0)
+
+
+def tool_input(payload: dict) -> dict:
+    value = payload.get('tool_input') or {}
+    return value if isinstance(value, dict) else {}
+
+
+def command_text(payload: dict) -> str:
+    value = tool_input(payload)
+    return str(value.get('command') or value.get('cmd') or '')
+
+
+def find_nexus_root(start: Path) -> Path | None:
+    current = start if start.is_dir() else start.parent
+    for candidate in (current, *current.parents):
+        if (candidate / '.nexus').exists() or (candidate / '_NEXUS_CONSTITUTION.md').exists():
+            return candidate
+    return None
+
+
+def repo_relative(path_text: str) -> tuple[Path, str] | None:
+    if not path_text:
+        return None
+    path_text = path_text.strip().strip('"\\'')
+    if path_text.startswith('/dev/null'):
+        return None
+    path = Path(path_text)
+    path = (Path.cwd() / path).resolve() if not path.is_absolute() else path.resolve()
+    root = find_nexus_root(path) or find_nexus_root(Path.cwd())
+    if root is None:
+        return None
+    try:
+        return root, path.relative_to(root).as_posix()
+    except ValueError:
+        return None
+
+
+def needs_claim(rel: str) -> bool:
+    if rel in ALLOW_WITHOUT_CLAIM:
+        return False
+    return not rel.startswith(ALLOW_PREFIXES)
+
+
+def lock_path(root: Path, rel: str) -> Path:
+    return root / '.nexus' / 'locks' / f"{rel.replace('/', '~2F')}.lock" / 'ts'
+
+
+def add_path(paths: set[tuple[Path, str]], path_text: str) -> None:
+    item = repo_relative(path_text)
+    if item:
+        paths.add(item)
+
+
+def patch_paths(command: str) -> set[tuple[Path, str]]:
+    paths: set[tuple[Path, str]] = set()
+    for line in command.splitlines():
+        match = re.match(r"^\\*\\*\\* (?:Update|Add|Delete) File: (.+)$", line.strip())
+        if match:
+            add_path(paths, match.group(1))
+        move = re.match(r"^\\*\\*\\* Move to: (.+)$", line.strip())
+        if move:
+            add_path(paths, move.group(1))
+    return paths
+
+
+def input_file_paths(payload: dict) -> set[tuple[Path, str]]:
+    paths: set[tuple[Path, str]] = set()
+    value = tool_input(payload)
+    for key in ('file_path', 'path'):
+        if isinstance(value.get(key), str):
+            add_path(paths, value[key])
+    return paths
+
+
+def bash_write_paths(command: str) -> set[tuple[Path, str]]:
+    paths: set[tuple[Path, str]] = set()
+    patterns = [
+        r"\\bmv\\s+([^;&|]+?)\\s+([^;&|]+)",
+        r"\\bcp\\s+([^;&|]+?)\\s+([^;&|]+)",
+        r">> ?([^;&|\\s]+)",
+        r"> ?([^;&|\\s]+)",
+    ]
+    for pattern in patterns:
+        for match in re.finditer(pattern, command):
+            for group in match.groups():
+                if not group:
+                    continue
+                for token in re.split(r"\\s+", group.strip()):
+                    add_path(paths, token)
+    return paths
+
+
+def missing_locks(paths: set[tuple[Path, str]]) -> list[tuple[Path, str]]:
+    missing = []
+    for root, rel in sorted(paths, key=lambda item: (str(item[0]), item[1])):
+        if needs_claim(rel) and not lock_path(root, rel).exists():
+            missing.append((root, rel))
+    return missing
+
+
+def claim_required_message(missing: list[tuple[Path, str]]) -> str:
+    shown = ', '.join(rel for _, rel in missing[:8]) + (' ...' if len(missing) > 8 else '')
+    first_root, first_rel = missing[0]
+    multi = '\\nIf multiple files are listed, claim each exact path.' if len(missing) > 1 else ''
+    return (
+        '⛔ CLAIM FIRST: '
+        + shown
+        + '\\n'
+        + f'cd {first_root} && nexus claim {first_rel} {NEXUS_AGENT} "Describe the edit"\\n'
+        + 'Retry edit. No workaround.'
+        + multi
+    )
+
+
+def main() -> None:
+    payload = load_payload()
+    command = command_text(payload)
+    tool_name = str(payload.get('tool_name') or '')
+    paths = input_file_paths(payload)
+
+    if tool_name == 'apply_patch' or command.startswith('*** Begin Patch'):
+        paths.update(patch_paths(command))
+    else:
+        paths.update(bash_write_paths(command))
+
+    missing = missing_locks(paths)
+    if missing:
+        block(claim_required_message(missing))
+
+
+if __name__ == '__main__':
+    main()
+`;
+}
+
+export default function hooks(args) {
+  const { agent, target, force } = parseArgs(args);
+  if (agent === 'all') {
+    for (const handle of Object.keys(HOOK_AGENT_CONFIGS)) {
+      installHook(handle, HOOK_AGENT_CONFIGS[handle].defaultTarget, force);
+    }
+    return;
+  }
+
+  installHook(agent, target, force);
+}
+
+function installHook(agent, target, force) {
+  const destination = expandHome(target);
+  const current = hookStatus(agent, target);
+
+  if (current.status === 'current' && !force) {
+    console.log(`Nexus ${HOOK_AGENT_CONFIGS[agent].label} hook already current at ${destination}`);
+    console.log('Run `nexus hooks install --force` to refresh it.');
+    return;
+  }
+
+  if (existsSync(destination) && current.status === 'foreign' && !force) {
+    console.log(`Hook file already exists at ${destination}`);
+    console.log('Run with `--force` after reviewing the existing file.');
+    return;
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  writeFileSync(destination, hookScriptContent(agent), 'utf-8');
+  chmodSync(destination, 0o755);
+
+  console.log(`Installed Nexus ${HOOK_AGENT_CONFIGS[agent].label} hook to ${destination}`);
+  console.log('Restart or refresh the agent session so the hook is loaded.');
+}