@phnx-labs/agents-cli 1.20.49 → 1.20.51

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;
 /**

package/dist/lib/hooks/cache.js

@@ -105,13 +105,19 @@ export function getHookShimPath(name) {
 /**
  * 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 function generateHookShim(args) {
     const shimsDir = args.paths?.shimsDir ?? getHookShimsDir();
     const cacheDir = args.paths?.cacheDir ?? getHookCacheDir();
     const logsDir = args.paths?.logsDir ?? getLogsDir();
     const shimPath = resolveContainedHookShimPath(shimsDir, args.name);
-    const content = renderShim(args.name, args.scriptPath, args.cache, { cacheDir, logsDir });
+    const content = renderShim(args.name, args.scriptPath, args.cache ?? null, args.matches, { cacheDir, logsDir });
     fs.mkdirSync(shimsDir, { recursive: true });
     let existing = null;
     if (fs.existsSync(shimPath)) {
@@ -132,24 +138,204 @@ export function generateHookShim(args) {
     }
     return shimPath;
 }
+/**
+ * The matches: gate, as a self-contained Python program run once per fire.
+ *
+ * Reads the hook's `matches:` block from $MATCHES_JSON and the event JSON from
+ * stdin, then prints `FIRE` or `SKIP`. A faithful port of `shouldFire()` in
+ * src/lib/hooks/match.ts — all declared predicates AND together, an empty block
+ * always fires, and the same ReDoS guard (`isSafeHookRegex`) rejects unsafe
+ * regexes to `SKIP`. Kept in double-quotes/apostrophe-free so it survives being
+ * embedded in a single-quoted `python -c '...'` argument in the shim. Behavioural
+ * parity with shouldFire() is pinned by a conformance test (match-parity.test.ts).
+ *
+ * On any exception it does NOT print SKIP — the shim treats a missing/garbled
+ * verdict as FIRE (fail-open), so a broken gate never silently disables a hook.
+ */
+const GATE_PY = `import json, os, re, subprocess, sys
+
+def arr(v):
+    if v is None:
+        return []
+    return v if isinstance(v, list) else [v]
+
+def max_group_depth(src):
+    depth = 0
+    mx = 0
+    escaped = False
+    in_class = False
+    for ch in src:
+        if escaped:
+            escaped = False
+            continue
+        if ch == chr(92):
+            escaped = True
+            continue
+        if ch == "[":
+            in_class = True
+            continue
+        if ch == "]":
+            in_class = False
+            continue
+        if in_class:
+            continue
+        if ch == "(":
+            depth += 1
+            if depth > mx:
+                mx = depth
+        elif ch == ")" and depth > 0:
+            depth -= 1
+    return mx
+
+_NESTED = re.compile(r"\\((?:\\?:)?[^)]*[*+][?+*{,\\d}]*[^)]*\\)\\s*(?:[+*]|\\{\\d*,?\\d*\\})")
+
+def is_safe(src):
+    if len(src) > 200:
+        return False
+    if max_group_depth(src) > 3:
+        return False
+    if _NESTED.search(src):
+        return False
+    return True
+
+def compile_rx(src):
+    if not is_safe(src):
+        return None
+    try:
+        return re.compile(src)
+    except re.error:
+        return None
+
+def find_root(start):
+    d = os.path.abspath(start)
+    while True:
+        if os.path.exists(os.path.join(d, ".git")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+def git_dirty(cwd):
+    try:
+        out = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL,
+        )
+        return len(out.stdout.decode().strip()) > 0
+    except Exception:
+        return False
+
+def should_fire():
+    m = json.loads(os.environ.get("MATCHES_JSON") or "{}")
+    if not m:
+        return True
+    try:
+        inp = json.load(sys.stdin)
+    except Exception:
+        inp = {}
+    cwd = inp.get("cwd") or os.getcwd()
+
+    v = m.get("prompt_contains")
+    if v is not None:
+        if v not in (inp.get("prompt") or ""):
+            return False
+
+    v = m.get("prompt_matches")
+    if v is not None:
+        rx = compile_rx(v)
+        if rx is None or not rx.search(inp.get("prompt") or ""):
+            return False
+
+    v = m.get("tool_name")
+    if v is not None:
+        allowed = arr(v)
+        if allowed:
+            tn = inp.get("tool_name")
+            if not tn or tn not in allowed:
+                return False
+
+    v = m.get("tool_args_match")
+    if v is not None:
+        ta = inp.get("tool_args")
+        ser = ta if isinstance(ta, str) else json.dumps(ta if ta is not None else "", separators=(",", ":"))
+        rx = compile_rx(v)
+        if rx is None or not rx.search(ser):
+            return False
+
+    v = m.get("cwd_includes")
+    if v is not None:
+        needles = arr(v)
+        if needles and not any(n in cwd for n in needles):
+            return False
+
+    v = m.get("project_has")
+    if v is not None:
+        root = find_root(cwd)
+        if not root or not os.path.exists(os.path.join(root, v)):
+            return False
+
+    v = m.get("git_dirty")
+    if v is not None:
+        if bool(v) != git_dirty(cwd):
+            return False
+
+    return True
+
+print("FIRE" if should_fire() else "SKIP")
+`;
+/**
+ * Gate-only pass-through tail: no caching, just run the underlying script with
+ * stdin forwarded and stdout/exit code propagated, plus one timing log line.
+ * Used when a hook declares \`matches:\` but no \`cache:\`.
+ */
+const PASSTHROUGH_TAIL = `now_ns() { "$PY" -c 'import time; print(int(time.time()*1e9))'; }
+START_NS=$(now_ns)
+EXIT=0
+if printf '%s' "$STDIN_PAYLOAD" | "$SOURCE"; then
+  EXIT=0
+else
+  EXIT=$?
+fi
+END_NS=$(now_ns)
+MS=$(( (END_NS - START_NS) / 1000000 ))
+TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%d}\\n' \\
+  "$TS" "$HOOK_NAME" "$MS" "none" "$EXIT" >>"$LOG_FILE" 2>/dev/null || true
+
+exit "$EXIT"`;
 /**
  * Render the bash shim. Bash 3.2-compatible (macOS default). Uses Python for
  * hashing + monotonic-ish nanosecond timing + portable mtime, resolved at
  * runtime (python3, then python) so a Windows Microsoft Store `python3` alias
  * stub — which exits non-zero without running — doesn't silently break caching.
+ *
+ * When `matches` is set, an early gate block evaluates the `matches:` predicates
+ * against the event JSON on stdin and exits 0 without running the script when
+ * they don't hold — this is the runtime enforcement of the documented `matches:`
+ * gating (mirrors `shouldFire()` in match.ts). When `cache` is null the shim is
+ * a gate-only pass-through: it forwards stdin to the script and its stdout back,
+ * with no cache read/write.
  */
-function renderShim(name, scriptPath, cache, paths) {
-    const ttl = typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0);
-    const key = cache.key ?? 'global';
-    const prefetch = cache.prefetch ?? 'none';
+function renderShim(name, scriptPath, cache, matches, paths) {
+    const ttl = cache ? (typeof cache.ttl === 'number' ? cache.ttl : (parseDuration(cache.ttl) ?? 0)) : 0;
+    const key = cache?.key ?? 'global';
+    const prefetch = cache?.prefetch ?? 'none';
     const { cacheDir, logsDir } = paths;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    const matchesJson = hasMatches ? JSON.stringify(matches) : '';
     // sh-escape: wrap in single quotes, escape any embedded single quotes.
     const q = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+    const cacheHeader = cache
+        ? `# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}`
+        : `# Cache: none (gate-only pass-through)`;
+    const matchesHeader = hasMatches ? `\n# Matches: ${matchesJson}` : '';
     return `#!/usr/bin/env bash
 # GENERATED by agents-cli. Do not edit — re-run \`agents hooks sync\` to refresh.
 # Hook: ${name}
 # Source: ${scriptPath}
-# Cache: key=${key} ttl=${ttl}s prefetch=${prefetch}
+${cacheHeader}${matchesHeader}
 set -u
 
 HOOK_NAME=${q(name)}
@@ -159,6 +345,7 @@ LOGS_DIR=${q(logsDir)}
 TTL=${ttl}
 PREFETCH=${q(prefetch)}
 KEY_MODE=${q(key)}
+MATCHES_JSON=${q(matchesJson)}
 
 mkdir -p "$CACHE_DIR" "$LOGS_DIR"
 
@@ -178,7 +365,33 @@ done
 # Read stdin once (Claude/Codex/Gemini pass JSON on stdin to every hook).
 STDIN_PAYLOAD="$(cat || true)"
 
-# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
+# --- matches: gate (issue #744 / RUSH-1506) -------------------------------
+# Enforce the hook's declared \`matches:\` predicates at fire time. Mirrors
+# shouldFire() in src/lib/hooks/match.ts: all declared predicates AND together;
+# an empty/absent block always fires. When the predicates don't hold we exit 0
+# WITHOUT running the script (a skipped hook is not an error). Fail-open: any
+# gate-eval error runs the script, so a broken predicate can never silently
+# disable a safety hook (e.g. git-guard).
+if [ -n "$MATCHES_JSON" ]; then
+  _GATE="$(printf '%s' "$STDIN_PAYLOAD" | MATCHES_JSON="$MATCHES_JSON" "$PY" -c ${q(GATE_PY)} 2>/dev/null || printf FIRE)"
+  [ -z "$_GATE" ] && _GATE=FIRE
+  if [ "$_GATE" = SKIP ]; then
+    _TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+    _LOG_FILE="$LOGS_DIR/events-$(date -u +%Y-%m-%d).jsonl"
+    printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":0,"cache":"skip","exit":0}\\n' \\
+      "$_TS" "$HOOK_NAME" >>"$_LOG_FILE" 2>/dev/null || true
+    exit 0
+  fi
+fi
+${cache ? CACHE_TAIL : PASSTHROUGH_TAIL}
+`;
+}
+/**
+ * Cache tail: the full cache lookup / stale-while-revalidate / timing machinery.
+ * Emitted only when the hook opts into \`cache:\`. (When only \`matches:\` is set,
+ * PASSTHROUGH_TAIL runs instead — no cache read/write.)
+ */
+const CACHE_TAIL = `# Portable sha1 — \`shasum\` is Perl, missing on minimal Linux images;
 # \`sha1sum\` is coreutils, missing on macOS. Truncate to 12 hex chars.
 sha1_12() { "$PY" -c 'import hashlib,sys; print(hashlib.sha1(sys.stdin.read().encode()).hexdigest()[:12])'; }
 
@@ -267,7 +480,6 @@ printf '{"ts":"%s","event":"hook.fire","hook":"%s","ms":%d,"cache":"%s","exit":%
 
 exit "$EXIT"
 `;
-}
 /**
  * Remove a hook's shim. Called by the registrar's garbage collection when a
  * hook is renamed/deleted or has its `cache:` field removed.

package/dist/lib/hooks.js

@@ -153,10 +153,12 @@ import { getHookShimsDir } from './state.js';
 /**
  * Resolve the command path to register for a hook.
  *
- * Returns either the raw script path (no `cache:` set, legacy behavior) or
- * the path to a generated caching/timing shim. The shim is written as a
- * side effect when `cache:` is configured. The agent-native settings file
- * gets the same shape either way — just a different command path.
+ * Returns either the raw script path (neither `cache:` nor `matches:` set,
+ * legacy behavior) or the path to a generated wrapper shim. The shim is written
+ * as a side effect when `cache:` and/or `matches:` is configured — it enforces
+ * the `matches:` gate at fire time and layers the caching/timing machinery when
+ * `cache:` is set. The agent-native settings file gets the same shape either
+ * way — just a different command path.
  */
 function resolveHookCommand(name, hookDef, resolveScript) {
     const scriptPath = resolveScript(hookDef.script);
@@ -165,13 +167,20 @@ function resolveHookCommand(name, hookDef, resolveScript) {
     if (!isValidHookShimName(name))
         return null;
     const cache = parseCacheConfig(hookDef.cache);
-    if (!cache) {
-        // No caching opted in — make sure a previously generated shim from an
-        // earlier `cache:` config is gone so the JSONL doesn't keep claiming hits.
+    const matches = hookDef.matches;
+    const hasMatches = matches != null && Object.keys(matches).length > 0;
+    if (!cache && !hasMatches) {
+        // No caching and no matches: gate opted in — make sure a previously
+        // generated shim from an earlier `cache:`/`matches:` config is gone so the
+        // JSONL doesn't keep claiming hits.
         removeHookShim(name);
         return toPortableCommand(scriptPath);
     }
-    return toPortableCommand(generateHookShim({ name, scriptPath, cache }));
+    // A shim is generated when the hook opts into caching and/or declares
+    // `matches:` predicates. The shim enforces the `matches:` gate at fire time
+    // (skipping the script when predicates don't hold) and, when `cache:` is set,
+    // layers the cache/timing machinery on top.
+    return toPortableCommand(generateHookShim({ name, scriptPath, cache, matches }));
 }
 /**
  * Extensions that are NEVER hooks — docs, configuration, plain data. A file

package/dist/lib/hosts/passthrough.js

@@ -91,6 +91,20 @@ export async function maybeRunOnHost(command, allArgs) {
     const spec = REMOTE_PASSTHROUGH[command];
     if (!spec)
         return false;
+    // Placement, not routing: `teams add`/`teams create` read `--device`/`--devices`
+    // (and `--host`/`--hosts`) as WHERE to place a teammate / the team pool — the
+    // command itself always runs locally on the orchestrator. Bail before the
+    // generic teams routing below so those flags reach the local action. Every
+    // other teams subcommand (`status`/`logs`/`stop`/…) keeps `--host` routing.
+    // Find the subcommand = the first non-flag token AFTER `teams` (robust to any
+    // leading global flags), then bail for the add/create aliases.
+    if (command === 'teams') {
+        const teamsIdx = allArgs.indexOf('teams');
+        const sub = teamsIdx >= 0 ? allArgs.slice(teamsIdx + 1).find((a) => !a.startsWith('-')) : undefined;
+        if (sub === 'add' || sub === 'a' || sub === 'create' || sub === 'c' || sub === 'new') {
+            return false;
+        }
+    }
     // `--device` is a first-class alias of `--host` (mirrors `agents run`); the
     // device registry is the source of truth for machine identity. Reject a
     // conflicting pair rather than silently preferring one — same rule as run.
@@ -101,6 +115,11 @@ export async function maybeRunOnHost(command, allArgs) {
         process.exitCode = 1;
         return true;
     }
+    // `--devices` / `--hosts` fan out to every registered device locally; don't
+    // let a per-host passthrough turn it into a cascading remote fan-out.
+    const fleetFlag = allArgs.includes('--devices') || allArgs.includes('--hosts');
+    if (fleetFlag)
+        return false;
     const hostName = hostFlag ?? deviceFlag;
     if (!hostName)
         return false;
@@ -142,7 +161,17 @@ export async function maybeRunOnHost(command, allArgs) {
         }
         return true;
     }
-    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, resolveRemoteOsSync(host.name));
+    // Doctor commands probe the agent CLIs; remote POSIX login shells often don't
+    // have the agents shims on PATH, which produces false "not installed" negatives.
+    // Bootstrap PATH with the canonical shim locations before the remote command.
+    // Windows is skipped: PowerShell usually has the shim dir via the install
+    // profile, and single-quoted env values would not expand $HOME/$PATH.
+    const isDoctorCommand = command === 'doctor' || (command === 'teams' && forwarded[1] === 'doctor');
+    const remoteOs = resolveRemoteOsSync(host.name);
+    const env = isDoctorCommand && !/^win/i.test((remoteOs ?? '').trim())
+        ? { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' }
+        : undefined;
+    const remoteCmd = buildRemoteAgentsInvocation(forwarded, remoteCwd, remoteOs, env);
     const code = sshStream(target, remoteCmd, { tty: interactive, multiplex: true });
     if (code === 255) {
         console.error(chalk.red(`${host.name}: unreachable over SSH (asleep, offline, or host key changed?).`) +

package/dist/lib/hosts/progress.d.ts

@@ -13,6 +13,37 @@
  * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
  * longer spawns thousands of ssh processes per hour on the laptop.
  */
+/**
+ * Cap for the LOCAL mirror of a distributed teammate's remote log. `followHostTask`
+ * appends remote bytes into the local mirror forever; a team can spin 10+ chatty
+ * remote teammates, so the orchestrator must keep a bounded window (the full log
+ * always lives on the host). The teams remote path (agents.ts readNewEvents) writes
+ * its own append into each teammate's `stdout.log`, then truncates that file to its
+ * trailing `REMOTE_MIRROR_MAX_BYTES` — the parser has already consumed the bytes
+ * (status/digest updated via lastReadPos), so trailing-tail history is dead weight.
+ */
+export declare const REMOTE_MIRROR_MAX_BYTES: number;
+/**
+ * Pull the new bytes of a remote log since `offset` in ONE ssh round-trip.
+ *
+ * The teams remote-teammate monitor calls this each poll to advance its offset-tail
+ * cursor into the host's log, mirroring only the delta into the local `stdout.log`
+ * the stream-json parser consumes. Byte-exact (raw Buffer, no UTF-8 decode) so a
+ * multibyte character split at the `tail -c` boundary neither drifts the offset nor
+ * renders as U+FFFD — the same discipline `fetchProgress` uses. `bytes.length` is
+ * the exact wire count; `newOffset` is `offset + bytes.length`.
+ *
+ * Returns null on a transient ssh failure (the caller retries next poll without
+ * advancing). `remoteLog` is a $HOME-prefixed path with a safe basename; it's
+ * shell-quoted defensively even so.
+ */
+export declare function pullRemoteLogDelta(target: string, opts: {
+    remoteLog: string;
+    offset: number;
+}): {
+    bytes: Buffer;
+    newOffset: number;
+} | null;
 export interface FollowOptions {
     remoteLog: string;
     remoteExit: string;