@phnx-labs/agents-cli 1.20.50 → 1.20.52

package/dist/lib/feed.d.ts

@@ -0,0 +1,56 @@
+export interface BlockOption {
+    label: string;
+    description?: string;
+}
+export interface BlockQuestion {
+    text: string;
+    header?: string;
+    options?: BlockOption[];
+    multiSelect?: boolean;
+}
+export interface OpenBlock {
+    blockId: string;
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+    ts: string;
+    questions: BlockQuestion[];
+    ticket?: string;
+    pr?: string;
+}
+/**
+ * Stable block id for a session. One block per session -- a new question
+ * replaces the previous one (the agent can only ask one question at a time).
+ */
+export declare function blockIdForSession(sessionId: string): string;
+/** Atomic write a block record to the feed store. */
+export declare function publishBlock(block: OpenBlock, root?: string): void;
+/** Read all block records. Returns them sorted by stable block filename. */
+export declare function listBlocks(root?: string): OpenBlock[];
+/** Remove a block record. Returns true if the file was deleted. */
+export declare function removeBlock(blockId: string, root?: string): boolean;
+/**
+ * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
+ * Embedded so it ships with the compiled CLI and can be installed to the
+ * CLI-writable user hooks dir without a separate file in the npm tarball.
+ */
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"PreToolUse hook: publish an open-block record when the agent calls\nAskUserQuestion, so `agents feed` can aggregate pending decisions.\n\nOutbound counterpart to the inbound mailbox-inject hook. Fires only on\nAskUserQuestion (matcher-gated in agents.yaml). Writes one block per session\nto ~/.agents/.history/feed/. A new question replaces the previous block.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    tool_input = payload.get(\"tool_input\", {})\n    questions = tool_input.get(\"questions\", [])\n    if not questions:\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    normalized_questions = []\n    for q in questions:\n        if not isinstance(q, dict):\n            continue\n        question = {\n            \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n            \"header\": q.get(\"header\"),\n            \"multiSelect\": q.get(\"multiSelect\", False),\n        }\n        raw_opts = q.get(\"options\", [])\n        if raw_opts:\n            question[\"options\"] = [\n                {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                for o in raw_opts\n                if isinstance(o, dict)\n            ]\n        normalized_questions.append(question)\n    if not normalized_questions:\n        return\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": datetime.now(timezone.utc).isoformat(),\n        \"questions\": normalized_questions,\n    }\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    os.makedirs(feed_dir, exist_ok=True)\n\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.rename(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+/** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
+export declare const FEED_PUBLISH_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    matcher: string;
+    script: string;
+    timeout: number;
+};
+/**
+ * Install the feed-publish hook script into the user hooks dir and add its
+ * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
+ * read-only mirror, so runtime-managed hooks must never write there.
+ * Idempotent -- skips if the script is already present and up to date.
+ */
+export declare function ensureFeedPublishHook(userAgentsDir?: string): {
+    installed: boolean;
+    error?: string;
+};

package/dist/lib/feed.js

@@ -0,0 +1,251 @@
+/**
+ * Feed store -- structured block records published by agents waiting on user
+ * input (AskUserQuestion). The outbound counterpart to the inbound mailbox:
+ * the mailbox delivers messages TO agents; the feed surfaces decisions agents
+ * need FROM the user.
+ *
+ * Layout: <feedDir>/<blockId>.json
+ *   Each file is one open block -- a question the agent asked. One block per
+ *   session: a new AskUserQuestion in the same session replaces the previous
+ *   block (an agent can only ask one question at a time). Removed when the
+ *   session advances past the block.
+ *
+ * A block carries enough identity (sessionId, mailboxId, host, runtime) for
+ * `agents feed` to aggregate across hosts and for `agents message` to route
+ * a reply back to the right agent.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getFeedDir, getUserAgentsDir } from './state.js';
+/**
+ * Stable block id for a session. One block per session -- a new question
+ * replaces the previous one (the agent can only ask one question at a time).
+ */
+export function blockIdForSession(sessionId) {
+    const safeSessionId = sessionId.replace(/[^A-Za-z0-9._-]/g, '-');
+    return `block-${safeSessionId}`;
+}
+function blockPath(root, blockId) {
+    if (!/^[A-Za-z0-9._-]+$/.test(blockId)) {
+        throw new Error(`Invalid feed block id: ${blockId}`);
+    }
+    return path.join(root, `${blockId}.json`);
+}
+/** Atomic write a block record to the feed store. */
+export function publishBlock(block, root) {
+    const dir = root ?? getFeedDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const target = blockPath(dir, block.blockId);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(block, null, 2), 'utf-8');
+    fs.renameSync(tmp, target);
+}
+/** Read all block records. Returns them sorted by stable block filename. */
+export function listBlocks(root) {
+    const dir = root ?? getFeedDir();
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const blocks = [];
+    for (const name of names.filter(n => n.endsWith('.json')).sort()) {
+        try {
+            const raw = fs.readFileSync(path.join(dir, name), 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (parsed.blockId && parsed.sessionId && parsed.questions?.length) {
+                blocks.push(parsed);
+            }
+        }
+        catch {
+            // skip corrupt / partial files
+        }
+    }
+    return blocks;
+}
+/** Remove a block record. Returns true if the file was deleted. */
+export function removeBlock(blockId, root) {
+    const dir = root ?? getFeedDir();
+    try {
+        fs.unlinkSync(blockPath(dir, blockId));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Hook installation
+// ---------------------------------------------------------------------------
+/**
+ * The feed-publish PreToolUse hook script (Python, mirroring 09-mailbox-inject.py).
+ * Embedded so it ships with the compiled CLI and can be installed to the
+ * CLI-writable user hooks dir without a separate file in the npm tarball.
+ */
+export const FEED_PUBLISH_HOOK_SCRIPT = `#!/usr/bin/env python3
+"""PreToolUse hook: publish an open-block record when the agent calls
+AskUserQuestion, so \`agents feed\` can aggregate pending decisions.
+
+Outbound counterpart to the inbound mailbox-inject hook. Fires only on
+AskUserQuestion (matcher-gated in agents.yaml). Writes one block per session
+to ~/.agents/.history/feed/. A new question replaces the previous block.
+
+Sub-agent gate: when the PreToolUse payload carries \`agent_type\`, this is a
+Task/Agent subagent -- skip. Only the top-level agent publishes. Verified on
+Claude Code 2.1.170 (2026-07).
+
+Fail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.
+"""
+import os
+import sys
+import json
+import re
+import socket
+import tempfile
+from datetime import datetime, timezone
+
+
+def main():
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        return
+
+    # Sub-agent gate.
+    if payload.get("agent_type"):
+        return
+
+    tool_input = payload.get("tool_input", {})
+    questions = tool_input.get("questions", [])
+    if not questions:
+        return
+
+    session_id = payload.get("session_id", "")
+    if not session_id:
+        return
+
+    normalized_questions = []
+    for q in questions:
+        if not isinstance(q, dict):
+            continue
+        question = {
+            "text": q.get("question", q.get("header", "")),
+            "header": q.get("header"),
+            "multiSelect": q.get("multiSelect", False),
+        }
+        raw_opts = q.get("options", [])
+        if raw_opts:
+            question["options"] = [
+                {"label": o.get("label", ""), "description": o.get("description")}
+                for o in raw_opts
+                if isinstance(o, dict)
+            ]
+        normalized_questions.append(question)
+    if not normalized_questions:
+        return
+
+    # Identity from env (set by agents-cli at spawn).
+    mailbox_id = os.path.basename(
+        os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
+    ) or session_id
+
+    hostname = os.environ.get("AGENTS_SYNC_MACHINE_ID") or socket.gethostname()
+    host = hostname.split(".")[0].strip().lower()
+    host = re.sub(r"[^a-z0-9_-]", "-", host) or "unknown"
+
+    runtime = os.environ.get("AGENTS_RUNTIME", "headless")
+
+    safe_session_id = re.sub(r"[^A-Za-z0-9._-]", "-", session_id)
+    block_id = f"block-{safe_session_id}"
+    block = {
+        "blockId": block_id,
+        "sessionId": session_id,
+        "mailboxId": mailbox_id,
+        "host": host,
+        "runtime": runtime,
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "questions": normalized_questions,
+    }
+
+    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a
+    # HOME override on every platform. Use the same anchor so hooks and the CLI
+    # always read/write one feed store (including temp-home and sandbox runs).
+    home = os.environ.get("HOME") or os.path.expanduser("~")
+    feed_dir = os.path.join(home, ".agents", ".history", "feed")
+    os.makedirs(feed_dir, exist_ok=True)
+
+    target = os.path.join(feed_dir, f"{block_id}.json")
+    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(block, f, indent=2)
+        os.rename(tmp, target)
+    except Exception:
+        try:
+            os.unlink(tmp)
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        pass  # fail open
+`;
+/** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
+export const FEED_PUBLISH_HOOK_MANIFEST = {
+    name: 'feed-publish',
+    events: ['PreToolUse'],
+    matcher: 'AskUserQuestion',
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
+/**
+ * Install the feed-publish hook script into the user hooks dir and add its
+ * manifest entry to the user agents.yaml. The system repo is an auto-pulled,
+ * read-only mirror, so runtime-managed hooks must never write there.
+ * Idempotent -- skips if the script is already present and up to date.
+ */
+export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
+    try {
+        const hooksDir = path.join(userAgentsDir, 'hooks');
+        const scriptPath = path.join(hooksDir, '10-feed-publish.py');
+        fs.mkdirSync(hooksDir, { recursive: true });
+        let installed = false;
+        if (!fs.existsSync(scriptPath) || fs.readFileSync(scriptPath, 'utf-8') !== FEED_PUBLISH_HOOK_SCRIPT) {
+            const tmpScript = `${scriptPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpScript, FEED_PUBLISH_HOOK_SCRIPT, { mode: 0o755 });
+            fs.renameSync(tmpScript, scriptPath);
+            installed = true;
+        }
+        const agentsYamlPath = path.join(userAgentsDir, 'agents.yaml');
+        const yamlDoc = fs.existsSync(agentsYamlPath)
+            ? yaml.parseDocument(fs.readFileSync(agentsYamlPath, 'utf-8'))
+            : new yaml.Document({});
+        if (yamlDoc.errors.length > 0) {
+            throw new Error(`Cannot install feed hook: ${agentsYamlPath} is invalid YAML`);
+        }
+        if (!yamlDoc.getIn(['hooks', 'feed-publish'])) {
+            yamlDoc.setIn(['hooks', 'feed-publish'], {
+                agents: ['claude'],
+                events: ['PreToolUse'],
+                matcher: 'AskUserQuestion',
+                script: '10-feed-publish.py',
+                timeout: 5,
+            });
+            const tmpYaml = `${agentsYamlPath}.${process.pid}.tmp`;
+            fs.writeFileSync(tmpYaml, String(yamlDoc));
+            fs.renameSync(tmpYaml, agentsYamlPath);
+            installed = true;
+        }
+        return { installed };
+    }
+    catch (err) {
+        return { installed: false, error: err.message };
+    }
+}

package/dist/lib/format.d.ts

@@ -0,0 +1,38 @@
+/** Print `msg` in red to stderr and exit the process with `code`. */
+export declare function die(msg: string, code?: number): never;
+/**
+ * Truncate `s` to at most `max` characters, appending a single-char ellipsis
+ * (`…`) when shortened. Character-count based (not ANSI/width aware — use
+ * `truncateToWidth` from `session/width.ts` for colored strings).
+ */
+export declare function truncate(s: string, max: number): string;
+/**
+ * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
+ * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
+ * variant that once lived in `cloud.ts` is deliberately dropped. (For the
+ * session-list long form with calendar fallback, see
+ * `formatRelativeTime` in `session/relative-time.ts`.)
+ */
+export declare function relTime(iso: string): string;
+/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
+export declare function humanDuration(ms: number): string;
+/**
+ * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
+ * wrappers). Matches the full CSI sequence including the `\x1b` escape.
+ */
+export declare function visibleWidth(s: string): number;
+/** Pad `s` with trailing spaces to a target character width. */
+export declare function padRight(s: string, width: number): string;
+/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
+export declare function padVisible(s: string, width: number): string;
+/** True when `--json` was passed or stdout is not a TTY. */
+export declare function isJsonMode(opts: {
+    json?: boolean;
+}): boolean;
+/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
+export declare function readStdinSync(): string;
+/**
+ * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
+ * stdout is a TTY; otherwise return `text` unchanged.
+ */
+export declare function termLink(text: string, filePath: string): string;

package/dist/lib/format.js

@@ -0,0 +1,108 @@
+/**
+ * Shared terminal-formatting helpers.
+ *
+ * These small utilities were previously copy-pasted across ~20 command and lib
+ * files, and had drifted into behavior differences (truncation ellipsis `...`
+ * vs `…` vs `.`; `relTime` long "5 minutes ago" vs short "5m ago"; a
+ * `visibleWidth` regex missing its `\x1b` escape). This module is the single
+ * canonical home — every consumer imports from here.
+ */
+import chalk from 'chalk';
+import { readSync } from 'node:fs';
+/** Print `msg` in red to stderr and exit the process with `code`. */
+export function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+/**
+ * Truncate `s` to at most `max` characters, appending a single-char ellipsis
+ * (`…`) when shortened. Character-count based (not ANSI/width aware — use
+ * `truncateToWidth` from `session/width.ts` for colored strings).
+ */
+export function truncate(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+/**
+ * Format an ISO timestamp as a compact relative age: "just now", "5m ago",
+ * "3h ago", "2d ago". The canonical short form — the long "5 minutes ago"
+ * variant that once lived in `cloud.ts` is deliberately dropped. (For the
+ * session-list long form with calendar fallback, see
+ * `formatRelativeTime` in `session/relative-time.ts`.)
+ */
+export function relTime(iso) {
+    const secs = Math.floor((Date.now() - new Date(iso).getTime()) / 1000);
+    if (secs < 10)
+        return 'just now';
+    if (secs < 60)
+        return `${secs}s ago`;
+    if (secs < 3600)
+        return `${Math.floor(secs / 60)}m ago`;
+    if (secs < 86400)
+        return `${Math.floor(secs / 3600)}h ago`;
+    return `${Math.floor(secs / 86400)}d ago`;
+}
+/** Format a millisecond duration as "45s", "3m", "2h 5m", "1d 3h". */
+export function humanDuration(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.floor(m / 60);
+    const mm = m % 60;
+    if (h < 24)
+        return mm ? `${h}h ${mm}m` : `${h}h`;
+    const d = Math.floor(h / 24);
+    const hh = h % 24;
+    return hh ? `${d}d ${hh}h` : `${d}d`;
+}
+/**
+ * Visible column width of `s`, ignoring ANSI SGR color codes (e.g. chalk
+ * wrappers). Matches the full CSI sequence including the `\x1b` escape.
+ */
+export function visibleWidth(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+/** Pad `s` with trailing spaces to a target character width. */
+export function padRight(s, width) {
+    return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+/** Pad `s` with trailing spaces to a target *visible* width (ANSI-aware). */
+export function padVisible(s, width) {
+    const w = visibleWidth(s);
+    return w >= width ? s : s + ' '.repeat(width - w);
+}
+/** True when `--json` was passed or stdout is not a TTY. */
+export function isJsonMode(opts) {
+    return Boolean(opts.json) || !process.stdout.isTTY;
+}
+/** Read all of stdin synchronously and return it UTF-8 decoded and trimmed. */
+export function readStdinSync() {
+    const chunks = [];
+    const buf = Buffer.alloc(65536);
+    while (true) {
+        let bytesRead;
+        try {
+            bytesRead = readSync(0, buf, 0, buf.length, null);
+        }
+        catch {
+            break;
+        }
+        if (bytesRead === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, bytesRead)));
+    }
+    return Buffer.concat(chunks).toString('utf-8').trim();
+}
+/**
+ * Wrap `text` in an OSC 8 hyperlink to `filePath` (as a `file://` URL) when
+ * stdout is a TTY; otherwise return `text` unchanged.
+ */
+export function termLink(text, filePath) {
+    if (!filePath || !process.stdout.isTTY)
+        return text;
+    const url = `file://${filePath}`;
+    return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}

package/dist/lib/git.d.ts

@@ -104,6 +104,27 @@ export declare function cloneIntoExisting(source: string, targetDir: string): Pr
     commit: string;
     error?: string;
 }>;
+/**
+ * Git-back an EXISTING, populated directory from a remote — clone it in place
+ * without deleting the local files. Turns a plain `~/.agents` folder (which setup
+ * creates as a bare `mkdirSync` and never git-clones — see state.ts ensureAgentsDir)
+ * into a real clone of the user's config remote, so `agents repo pull/push` and
+ * `agents sync` work on a fresh or Windows machine that never got the manual clone.
+ *
+ * Unlike cloneIntoExisting (which blindly `checkout .`s over local files), this
+ * BACKS UP every tracked file whose local copy differs from the remote — into a
+ * sibling `<dir>.pre-adopt-backup/` OUTSIDE the repo so it can't be re-committed —
+ * before overwriting it. So a box with local edits to agents.yaml/hooks/rules
+ * doesn't silently lose them. Untracked runtime state (.cache/.history/.system,
+ * all gitignored) is never touched because `checkout .` only restores tracked paths.
+ */
+export declare function adoptRepo(source: string, targetDir: string): Promise<{
+    success: boolean;
+    commit: string;
+    backupDir?: string;
+    backedUp: string[];
+    error?: string;
+}>;
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/git.js

@@ -462,6 +462,98 @@ export async function cloneIntoExisting(source, targetDir) {
         return { success: false, commit: '', error: err.message };
     }
 }
+/**
+ * Git-back an EXISTING, populated directory from a remote — clone it in place
+ * without deleting the local files. Turns a plain `~/.agents` folder (which setup
+ * creates as a bare `mkdirSync` and never git-clones — see state.ts ensureAgentsDir)
+ * into a real clone of the user's config remote, so `agents repo pull/push` and
+ * `agents sync` work on a fresh or Windows machine that never got the manual clone.
+ *
+ * Unlike cloneIntoExisting (which blindly `checkout .`s over local files), this
+ * BACKS UP every tracked file whose local copy differs from the remote — into a
+ * sibling `<dir>.pre-adopt-backup/` OUTSIDE the repo so it can't be re-committed —
+ * before overwriting it. So a box with local edits to agents.yaml/hooks/rules
+ * doesn't silently lose them. Untracked runtime state (.cache/.history/.system,
+ * all gitignored) is never touched because `checkout .` only restores tracked paths.
+ */
+export async function adoptRepo(source, targetDir) {
+    const trimmed = source.trim();
+    if (fs.existsSync(path.join(targetDir, '.git'))) {
+        return { success: false, commit: '', backedUp: [], error: 'Already a git repo — nothing to adopt' };
+    }
+    // Preserve the user's transport. `parseSource` THROWS for `ssh://` and any
+    // non-github `git@host:` URL, and rewrites `git@github.com:x` → https (breaking
+    // SSH-key-only auth — the common config-repo setup — so a private clone hangs on
+    // a credential prompt). So for an SSH URL, clone it AS-IS and never call
+    // parseSource; for everything else, normalize + reject local via parseSource —
+    // inside the try, so a malformed URL returns a graceful error, not a stack trace.
+    const isSsh = trimmed.startsWith('git@') || trimmed.startsWith('ssh://');
+    const tempDir = path.join(targetDir, '.git-adopt-temp');
+    try {
+        let cloneUrl;
+        let ref;
+        if (isSsh) {
+            cloneUrl = trimmed; // SSH stays SSH; clone the remote's default HEAD.
+        }
+        else {
+            const parsed = parseSource(source);
+            if (parsed.type === 'local') {
+                return { success: false, commit: '', backedUp: [], error: 'Cannot adopt from a local source' };
+            }
+            cloneUrl = parsed.url;
+            ref = parsed.ref;
+        }
+        assertSafeGitTransport(cloneUrl);
+        fs.mkdirSync(targetDir, { recursive: true });
+        // Idempotency: clear a stale temp left by an interrupted prior run.
+        if (fs.existsSync(tempDir))
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        // Clone to temp, then move its .git in so the index == remote HEAD.
+        // Fail fast on a missing credential instead of hanging on a prompt: set
+        // GIT_TERMINAL_PROMPT=0 on the inherited env directly rather than via
+        // simple-git's `.env()`, which validates and rejects command-like vars the
+        // harness may set (GIT_EDITOR, PAGER, …) — the child inherits process.env,
+        // and non-interactive git is what we always want in the CLI anyway.
+        process.env.GIT_TERMINAL_PROMPT = '0';
+        await simpleGit().clone(cloneUrl, tempDir);
+        const repoGit = simpleGit(tempDir);
+        if (ref)
+            await repoGit.checkout(ref);
+        fs.renameSync(path.join(tempDir, '.git'), path.join(targetDir, '.git'));
+        fs.rmSync(tempDir, { recursive: true, force: true });
+        const targetGit = simpleGit(targetDir);
+        // Back up any TRACKED file whose local copy differs from the remote before the
+        // checkout clobbers it. `diff --name-only` (worktree vs the moved-in index) is
+        // exactly that set; a deleted-locally file has nothing to preserve.
+        const diff = await targetGit.diff(['--name-only']);
+        const clobbered = diff.split('\n').map((s) => s.trim()).filter(Boolean);
+        let backupDir;
+        const backedUp = [];
+        if (clobbered.length > 0) {
+            backupDir = path.join(path.dirname(targetDir), path.basename(targetDir) + '.pre-adopt-backup');
+            for (const rel of clobbered) {
+                const src = path.join(targetDir, rel);
+                if (!fs.existsSync(src))
+                    continue;
+                const dst = path.join(backupDir, rel);
+                fs.mkdirSync(path.dirname(dst), { recursive: true });
+                fs.copyFileSync(src, dst);
+                backedUp.push(rel);
+            }
+        }
+        // Materialize the remote's tracked files (respects .gitignore, so
+        // .cache/.history/.system stay put), overwriting the now-backed-up locals.
+        await targetGit.checkout('.');
+        installGithooksSymlinks(targetDir);
+        const log = await targetGit.log({ maxCount: 1 });
+        return { success: true, commit: log.latest?.hash.slice(0, 8) || 'unknown', backupDir, backedUp };
+    }
+    catch (err) {
+        if (fs.existsSync(tempDir))
+            fs.rmSync(tempDir, { recursive: true, force: true });
+        return { success: false, commit: '', backedUp: [], error: err.message };
+    }
+}
 /**
  * Check if the repo's origin points to the system repo.
  */

package/dist/lib/hooks/cache.d.ts

@@ -1,4 +1,4 @@
-import type { HookCache, HookCacheConfig } from '../types.js';
+import type { HookCache, HookCacheConfig, HookMatches } from '../types.js';
 /**
  * Parse a `cache:` value from hooks.yaml into the canonical config form.
  * Accepts the shorthand string ("5m", "30s-bg") or the full object form.
@@ -30,11 +30,18 @@ export interface HookShimPaths {
 /**
  * Generate (or refresh) the shim script for a hook. Idempotent — only writes
  * when the content differs from what's on disk. Returns the absolute shim path.
+ *
+ * A shim is generated when the hook opts into caching (`cache`) and/or declares
+ * `matches:` predicates. When `matches` is present the shim gates execution on
+ * those predicates before running the underlying script (see `renderShim`);
+ * when `cache` is absent the shim is a thin pass-through wrapper that only
+ * applies the gate and forwards stdin/stdout unchanged.
  */
 export declare function generateHookShim(args: {
     name: string;
     scriptPath: string;
-    cache: HookCacheConfig;
+    cache?: HookCacheConfig | null;
+    matches?: HookMatches;
     paths?: HookShimPaths;
 }): string;
 /**