thalixtower-cli 0.6.0

package/README.md

@@ -0,0 +1,63 @@
+# thalixtower-cli — `atc`
+
+The Thalix Tower CLI. Coordinate multiple coding agents working one repo: claim
+scope before editing, get inline conflict verdicts, share a decision log, and
+receive your **standing orders** at every checkin. Also the terminal for humans —
+`atc login` manages projects, tokens, and standing orders without the dashboard.
+
+## Install
+
+```bash
+npm i -g thalixtower-cli
+```
+
+## Wire a repo (fast path)
+
+```bash
+atc init          # scaffolds .mcp.json + the AGENTS.md compliance block + .gitignore
+```
+
+## Agent plane (frequency token)
+
+Get a **frequency token** (dashboard https://tower.thalixinc.ai → project →
+Mint token, or `atc tokens mint` after login), then:
+
+```bash
+export ATC_TOKEN=atcf_…        # required
+# export ATC_API=…            # optional; defaults to the hosted prod API
+```
+
+```bash
+atc checkin --task "refactor auth"   # contact the Tower; the brief arrives with
+                                     # your standing orders first — follow them
+atc standing                         # your assigned standing orders, in full
+atc brief                            # roster + claims + conflicts + NOTAMs
+atc claim "src/auth/**"              # request scope; exit code 3 if it conflicts
+atc squawk "rewriting User model"    # status + heartbeat
+atc note "auth uses JWT, 15min TTL"  # decision log (--pin to pin; note show <id> for full)
+atc standing propose handoff --body "…"  # propose a DRAFT standing order (a human assigns)
+atc clear ["src/auth/**"]            # release scope (all, or one glob)
+atc checkout                         # leave; releases your claims
+```
+
+## Human plane (`atc login`)
+
+```bash
+atc login                            # opens the browser; approve; 30-day session
+atc whoami / atc logout
+
+atc projects [create "<name>"]
+atc tokens --project <p>             # list (shows each token's alignment)
+atc tokens mint --project <p> --label colby --orders relay-agent
+atc tokens align <tokenId> --orders a,b | --default
+atc standing ls|show|create|edit|rm|assign --project <p>
+```
+
+**Standing orders** are a per-project library of named instructions. Which orders
+an agent receives is decided by its token's **alignment** (`mint --orders`,
+realign anytime — it lands at the agent's next brief); unaligned tokens get the
+project default set (`atc standing assign`).
+
+Agent session state lives in `.atc/` in the worktree (gitignore it); your login
+session lives in `~/.config/atc/`. Add `--json` to any command for
+machine-readable output. Full protocol: https://tower.thalixinc.ai/docs

package/bin/atc.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Thin launcher → compiled CLI. Build with `npm run build` (tsc → dist/).
+require('../dist/index.js');

package/dist/client.js

@@ -0,0 +1,125 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSession = exports.saveSession = exports.DEFAULT_API = void 0;
+exports.loadConfig = loadConfig;
+exports.workspaceId = workspaceId;
+exports.clearSession = clearSession;
+exports.api = api;
+exports.currentBranch = currentBranch;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+/**
+ * Thin client for the Thalix Tower /v1 API + local session state.
+ * Config is env-only (ATC_API / ATC_TOKEN). `.atc/` holds:
+ *   workspace.json  { workspaceId }   — persistent takeover identity (ADR-0003)
+ *   session.json    { callsign, sessionToken, api }  — lease-bound; cleared on checkout
+ * Both live in the worktree and must be gitignored.
+ */
+const ATC_DIR = path.join(process.cwd(), '.atc');
+const WORKSPACE_FILE = path.join(ATC_DIR, 'workspace.json');
+const SESSION_FILE = path.join(ATC_DIR, 'session.json');
+/** Prod Tower API. Override with ATC_API (e.g. the dev stack). */
+exports.DEFAULT_API = 'https://api.tower.thalixinc.ai';
+function loadConfig() {
+    return {
+        api: (process.env.ATC_API || exports.DEFAULT_API).replace(/\/$/, ''),
+        token: process.env.ATC_TOKEN ?? '',
+    };
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(file, data) {
+    fs.mkdirSync(ATC_DIR, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2));
+}
+/** Stable per-checkout workspace id (created once, survives checkout). */
+function workspaceId() {
+    const existing = readJson(WORKSPACE_FILE);
+    if (existing?.workspaceId)
+        return existing.workspaceId;
+    const id = `ws_${(0, node_crypto_1.randomUUID)()}`;
+    writeJson(WORKSPACE_FILE, { workspaceId: id });
+    return id;
+}
+const saveSession = (s) => writeJson(SESSION_FILE, s);
+exports.saveSession = saveSession;
+const loadSession = () => readJson(SESSION_FILE);
+exports.loadSession = loadSession;
+function clearSession() {
+    try {
+        fs.rmSync(SESSION_FILE);
+    }
+    catch {
+        /* already gone */
+    }
+}
+async function api(cfg, bearer, method, apiPath, body) {
+    const res = await fetch(`${cfg.api}${apiPath}`, {
+        method,
+        headers: {
+            authorization: `Bearer ${bearer}`,
+            'content-type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = { error: text };
+    }
+    return { status: res.status, ok: res.ok, body: parsed };
+}
+/** Best-effort current git branch for display. */
+function currentBranch() {
+    try {
+        const head = fs.readFileSync(path.join(process.cwd(), '.git', 'HEAD'), 'utf8').trim();
+        const m = /ref:\s+refs\/heads\/(.+)/.exec(head);
+        return m ? m[1] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hook.js

@@ -0,0 +1,440 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.editPaths = editPaths;
+exports.runHook = runHook;
+exports.runAudit = runAudit;
+exports.installHooks = installHooks;
+/**
+ * atc hook — the Tier-3 compliance client (Rev-001 §A / Rev-002 Phase 3).
+ *
+ * Wired into Claude Code's hook system (`atc hook install`), it makes the
+ * protocol automatic: session-start injects the brief (standing orders first),
+ * prompt-submit heartbeats and surfaces traffic/conflicts, pre-edit auto-claims
+ * the file being touched and surfaces the inline conflict verdict.
+ *
+ * Non-negotiables (ADR-0004): FAIL-OPEN always (the Tower must never brick a
+ * session — any failure exits 0 with one stderr warning per session); NEVER
+ * blocks an edit (no permissionDecision is ever emitted); at most one network
+ * call per path per session (local cache in .atc/hook-state.json).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const client_1 = require("./client");
+const PRE_EDIT_TIMEOUT_MS = Number(process.env.ATC_HOOK_TIMEOUT_MS || 300);
+const SESSION_START_TIMEOUT_MS = 2500; // checkin+brief may ride a cold start
+const HEARTBEAT_TIMEOUT_MS = 800;
+const HEARTBEAT_MIN_MS = 60_000; // prompt-submit fires every turn; squawk at most this often
+const COALESCE_THRESHOLD = 20; // >N file claims under one top dir → one dir/** claim
+const ATTEMPTED_RETRIES_PER_CALL = 2;
+const STATE_FILE = path.join(process.cwd(), '.atc', 'hook-state.json');
+function loadState() {
+    try {
+        const s = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+        return { claimed: {}, edited: [], coalesced: [], ...s };
+    }
+    catch {
+        return { claimed: {}, edited: [], coalesced: [] };
+    }
+}
+function saveState(state) {
+    try {
+        fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+        fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+    }
+    catch {
+        /* fail-open */
+    }
+}
+function warnOnce(state, msg) {
+    if (state.towerWarned)
+        return;
+    state.towerWarned = true;
+    process.stderr.write(`atc hook: ${msg} — coordination disabled for this session (edits unaffected)\n`);
+}
+// ---------------------------------------------------------------------------
+// Fail-open HTTP with a hard client budget
+// ---------------------------------------------------------------------------
+async function timedApi(cfg, bearer, method, apiPath, body, timeoutMs) {
+    try {
+        const res = await fetch(`${cfg.api}${apiPath}`, {
+            method,
+            headers: { authorization: `Bearer ${bearer}`, 'content-type': 'application/json' },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        const text = await res.text();
+        let parsed = {};
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = {};
+        }
+        return { ok: res.ok, status: res.status, body: parsed };
+    }
+    catch {
+        return null; // timeout / network — caller fails open
+    }
+}
+/**
+ * One session per workspace: reuse .atc/session.json; checkin only when it is
+ * missing or rejected (then write back for the CLI/MCP to pick up).
+ */
+async function ensureSession(cfg, timeoutMs) {
+    const existing = (0, client_1.loadSession)();
+    if (existing)
+        return existing;
+    if (!cfg.token)
+        return null;
+    const r = await timedApi(cfg, cfg.token, 'POST', '/v1/sessions', {
+        workspaceId: (0, client_1.workspaceId)(),
+        cli: process.env.ATC_CLI || 'claude-code',
+        worktree: process.cwd(),
+        branch: (0, client_1.currentBranch)(),
+        task: 'hooked session',
+    }, timeoutMs);
+    if (!r?.ok)
+        return null;
+    const session = { callsign: r.body.callsign, sessionToken: r.body.sessionToken, api: cfg.api };
+    (0, client_1.saveSession)(session);
+    return session;
+}
+/** Session-token call with one re-checkin retry on 401 (token may have rotated). */
+async function sessionApi(cfg, method, apiPath, body, timeoutMs) {
+    const session = await ensureSession(cfg, timeoutMs);
+    if (!session)
+        return null;
+    let r = await timedApi(cfg, session.sessionToken, method, apiPath, body, timeoutMs);
+    if (r && r.status === 401 && cfg.token) {
+        // Stale session.json (another client took over and checked out) → re-checkin once.
+        try {
+            fs.rmSync(path.join(process.cwd(), '.atc', 'session.json'));
+        }
+        catch { /* ignore */ }
+        const fresh = await ensureSession(cfg, timeoutMs);
+        if (!fresh)
+            return r;
+        r = await timedApi(cfg, fresh.sessionToken, method, apiPath, body, timeoutMs);
+    }
+    return r;
+}
+function readPayload() {
+    try {
+        if (process.stdin.isTTY)
+            return {};
+        const raw = fs.readFileSync(0, 'utf8');
+        return raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+function emitContext(hookEventName, text) {
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext: text } }) + '\n');
+}
+/** Files an edit tool is about to touch, relative to the workspace. */
+function editPaths(toolName, toolInput, cwd) {
+    if (!toolInput)
+        return [];
+    const raw = [];
+    if (typeof toolInput.file_path === 'string')
+        raw.push(toolInput.file_path);
+    if (typeof toolInput.notebook_path === 'string')
+        raw.push(toolInput.notebook_path);
+    if (Array.isArray(toolInput.edits)) {
+        for (const e of toolInput.edits) {
+            if (e && typeof e.file_path === 'string')
+                raw.push(e.file_path);
+        }
+    }
+    void toolName;
+    const out = [];
+    for (const p of raw) {
+        const rel = path.isAbsolute(p) ? path.relative(cwd, p) : p;
+        // Outside the workspace (or weird) → not repo scope, don't claim it.
+        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+            continue;
+        const norm = rel.split(path.sep).join('/');
+        if (!out.includes(norm))
+            out.push(norm);
+    }
+    return out;
+}
+function renderVerdict(relPath, conflicts) {
+    const lines = conflicts
+        .map((c) => `${c.by} holds ${c.theirGlob} (${c.status}, seen ${c.lastSeen})`)
+        .join('; ');
+    return (`⚠ Thalix Tower conflict on ${relPath}: ${lines}. ` +
+        `The claim is advisory — you may proceed, but coordinate: squawk blocked and surface this to the human if the overlap is real.`);
+}
+function renderBrief(b) {
+    const parts = ['[Thalix Tower brief]'];
+    if (b.standing?.body) {
+        parts.push(`STANDING ORDERS (${(b.standing.orders ?? []).map((o) => o.name).join(', ')}) — follow these:\n${b.standing.body}`);
+    }
+    const others = (b.roster ?? []).filter((r) => r.callsign !== b.you?.callsign);
+    if (others.length) {
+        parts.push('On frequency: ' +
+            others.map((r) => `${r.callsign} (${r.code ?? r.statusText ?? 'working'}, ${r.claimCount} claims)`).join(', '));
+    }
+    if ((b.conflictsWithMine ?? []).length) {
+        parts.push('CONFLICTS touching you: ' + b.conflictsWithMine.map((c) => `${c.by}:${c.theirGlob} vs ${c.glob}`).join('; '));
+    }
+    if (b.traffic?.unacked > 0) {
+        parts.push(`✉ ${b.traffic.unacked} unacked message(s): ` +
+            (b.traffic.preview ?? []).map((m) => `${m.from}: "${m.body}"`).join(' · ') +
+            ' — read with atc_traffic and answer with atc_call.');
+    }
+    if ((b.notams ?? []).length) {
+        parts.push('Recent NOTAMs: ' + b.notams.slice(0, 5).map((n) => `[${n.id}] ${n.body.slice(0, 80)}`).join(' · '));
+    }
+    parts.push(`(You are ${b.you?.callsign}. Claims are auto-derived from your edits by the Tower hook.)`);
+    return parts.join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+async function runSessionStart(payload) {
+    const cfg = (0, client_1.loadConfig)();
+    if (!cfg.token && !(0, client_1.loadSession)())
+        return; // not a Tower-wired repo
+    const state = loadState();
+    // New host session → fresh per-session caches (claims on the board persist).
+    if (payload.session_id && payload.session_id !== state.sessionId) {
+        state.sessionId = payload.session_id;
+        state.claimed = {};
+        state.edited = [];
+        state.coalesced = [];
+        state.towerWarned = false;
+    }
+    const r = await sessionApi(cfg, 'GET', '/v1/brief', undefined, SESSION_START_TIMEOUT_MS);
+    if (!r?.ok) {
+        warnOnce(state, 'Tower unreachable at session start');
+        saveState(state);
+        return;
+    }
+    state.lastHeartbeat = Date.now();
+    saveState(state);
+    emitContext('SessionStart', renderBrief(r.body));
+}
+async function runPrompt() {
+    const cfg = (0, client_1.loadConfig)();
+    if (!cfg.token && !(0, client_1.loadSession)())
+        return;
+    const state = loadState();
+    if (state.lastHeartbeat && Date.now() - state.lastHeartbeat < HEARTBEAT_MIN_MS)
+        return;
+    state.lastHeartbeat = Date.now(); // even on failure — don't hammer a down Tower
+    const r = await sessionApi(cfg, 'POST', '/v1/squawk', {}, HEARTBEAT_TIMEOUT_MS);
+    saveState(state);
+    if (!r?.ok)
+        return; // heartbeat is best-effort; no warning needed here
+    const parts = [];
+    if ((r.body.conflictsWithMine ?? []).length) {
+        parts.push('⚠ Thalix Tower: conflicts on your claims — ' +
+            r.body.conflictsWithMine.map((c) => `${c.by}:${c.theirGlob} vs ${c.glob}`).join('; '));
+    }
+    if (r.body.unackedTraffic > 0) {
+        parts.push(`✉ Thalix Tower: ${r.body.unackedTraffic} unacked message(s) — ` +
+            (r.body.trafficPreview ?? []).map((m) => `${m.from}: "${m.body}"`).join(' · ') +
+            ' — read with atc_traffic and answer with atc_call.');
+    }
+    if (parts.length)
+        emitContext('UserPromptSubmit', parts.join('\n'));
+}
+/** Top-level dir → claimed-file count, for coalescing. */
+function coalesceCandidate(state) {
+    const counts = new Map();
+    for (const p of Object.keys(state.claimed)) {
+        if (state.claimed[p] !== 'claimed' || !p.includes('/'))
+            continue;
+        const top = p.split('/')[0];
+        counts.set(top, (counts.get(top) ?? 0) + 1);
+    }
+    for (const [dir, n] of counts) {
+        if (n > COALESCE_THRESHOLD && !state.coalesced.includes(dir))
+            return dir;
+    }
+    return null;
+}
+async function runPreEdit(payload) {
+    const cfg = (0, client_1.loadConfig)();
+    if (!cfg.token && !(0, client_1.loadSession)())
+        return;
+    const cwd = payload.cwd || process.cwd();
+    const paths = editPaths(payload.tool_name, payload.tool_input, cwd);
+    if (paths.length === 0)
+        return;
+    const state = loadState();
+    for (const p of paths)
+        if (!state.edited.includes(p))
+            state.edited.push(p);
+    // Already-claimed (or coalesced-covered) paths cost nothing.
+    const covered = (p) => state.claimed[p] === 'claimed' || state.coalesced.some((d) => p.startsWith(`${d}/`));
+    const toClaim = paths.filter((p) => !covered(p));
+    if (toClaim.length === 0) {
+        saveState(state);
+        return;
+    }
+    // Piggyback: retry previously timed-out paths ONCE; a second failure drops
+    // them for the session (ADR-0004 — bounded retries, no hammering).
+    const attempted = Object.keys(state.claimed)
+        .filter((p) => state.claimed[p] === 'attempted')
+        .slice(0, ATTEMPTED_RETRIES_PER_CALL);
+    const verdicts = [];
+    await Promise.all([...toClaim, ...attempted].map(async (p) => {
+        const isRetry = attempted.includes(p);
+        const r = await sessionApi(cfg, 'POST', '/v1/claims', { glob: p, kind: 'file' }, PRE_EDIT_TIMEOUT_MS);
+        if (!r) {
+            state.claimed[p] = isRetry ? 'dropped' : 'attempted';
+            warnOnce(state, 'claim timed out');
+            return;
+        }
+        if (!r.ok) {
+            warnOnce(state, `claim rejected (${r.status})`);
+            return;
+        }
+        state.claimed[p] = 'claimed';
+        if ((r.body.conflicts ?? []).length && toClaim.includes(p)) {
+            verdicts.push(renderVerdict(p, r.body.conflicts));
+        }
+    }));
+    // Coalesce when one directory accumulates too many file claims.
+    const dir = coalesceCandidate(state);
+    if (dir) {
+        const r = await sessionApi(cfg, 'POST', '/v1/claims', { glob: `${dir}/**`, kind: 'glob' }, PRE_EDIT_TIMEOUT_MS);
+        if (r?.ok)
+            state.coalesced.push(dir);
+    }
+    saveState(state);
+    if (verdicts.length)
+        emitContext('PreToolUse', verdicts.join('\n'));
+}
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+/** `atc hook run <event>` — ALWAYS exits 0; the Tower never breaks a session. */
+async function runHook(event) {
+    try {
+        const payload = readPayload();
+        if (event === 'session-start')
+            await runSessionStart(payload);
+        else if (event === 'prompt')
+            await runPrompt();
+        else if (event === 'pre-edit')
+            await runPreEdit(payload);
+        // unknown events: silently no-op (forward compat)
+    }
+    catch {
+        /* fail-open — never disturb the session */
+    }
+    process.exit(0);
+}
+/** `atc audit` — compliance rate from the hook's own per-session record. */
+function runAudit(json) {
+    const state = loadState();
+    const edited = state.edited;
+    const covered = edited.filter((p) => state.claimed[p] === 'claimed' || state.coalesced.some((d) => p.startsWith(`${d}/`)));
+    const rate = edited.length === 0 ? 1 : covered.length / edited.length;
+    const data = {
+        edited: edited.length,
+        claimed: covered.length,
+        attempted: Object.values(state.claimed).filter((v) => v === 'attempted' || v === 'dropped').length,
+        complianceRate: Math.round(rate * 100) / 100,
+    };
+    if (json) {
+        process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    }
+    else {
+        process.stdout.write(edited.length === 0
+            ? 'no edits recorded by the hook this session\n'
+            : `compliance: ${covered.length}/${edited.length} edited paths claimed before edit (${Math.round(rate * 100)}%)` +
+                (data.attempted ? ` · ${data.attempted} attempted (Tower slow/down)` : '') +
+                '\n');
+    }
+}
+// ---------------------------------------------------------------------------
+// `atc hook install` — wire .claude/settings.json (idempotent, plan + confirm)
+// ---------------------------------------------------------------------------
+const HOOK_ENTRIES = {
+    SessionStart: { command: 'atc hook run session-start', timeout: 10 },
+    UserPromptSubmit: { command: 'atc hook run prompt', timeout: 5 },
+    PreToolUse: { matcher: 'Edit|Write|MultiEdit|NotebookEdit', command: 'atc hook run pre-edit', timeout: 5 },
+};
+function installHooks(opts) {
+    const file = path.join(process.cwd(), '.claude', 'settings.json');
+    let settings = {};
+    try {
+        settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        /* fresh file */
+    }
+    const hooks = settings.hooks ?? {};
+    const additions = [];
+    for (const [event, spec] of Object.entries(HOOK_ENTRIES)) {
+        const groups = hooks[event] ?? [];
+        const present = groups.some((g) => (g.hooks ?? []).some((h) => typeof h.command === 'string' && h.command.includes('atc hook run')));
+        if (present)
+            continue;
+        const entry = { hooks: [{ type: 'command', command: spec.command, timeout: spec.timeout }] };
+        if (spec.matcher)
+            entry.matcher = spec.matcher;
+        groups.push(entry);
+        hooks[event] = groups;
+        additions.push(`${event}${spec.matcher ? ` (${spec.matcher})` : ''} → ${spec.command}`);
+    }
+    if (additions.length === 0) {
+        if (!opts.json)
+            process.stdout.write('hooks already installed — nothing to do\n');
+        return { changed: false };
+    }
+    if (!opts.json) {
+        process.stdout.write('atc hook install — will add to .claude/settings.json:\n');
+        for (const a of additions)
+            process.stdout.write(`  + ${a}\n`);
+        process.stdout.write('\nThe hook fails open (Tower down → edits unaffected) and never blocks a tool call.\n' +
+            'Claude Code will ask you to approve these project hooks on first run.\n');
+    }
+    settings.hooks = hooks;
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+    if (!opts.json)
+        process.stdout.write(`\nwrote .claude/settings.json\n`);
+    else
+        process.stdout.write(JSON.stringify({ added: additions }, null, 2) + '\n');
+    return { changed: true };
+}