@cosmovex/agentpager 0.1.0

package/dist/guard/bin.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// A separate entry point, on purpose.
+//
+// This runs once per tool call, so it must not import the relay, Firebase or the agent SDK the way
+// `cli.ts` does. Going through the main CLI made the hook hang outright — Firebase's module-level
+// init keeps the event loop alive, so the process wrote its answer and then never exited, and Claude
+// Code sat waiting on a hook that had already decided. Fewer imports here is not a micro-optimisation;
+// it is the difference between working and not.
+import { runRuleCommand, USAGE } from './cli.js';
+import { install, runDeskHook, runHook, status, uninstall } from './index.js';
+const arg = process.argv[2];
+try {
+    switch (arg) {
+        case undefined:
+            await runHook();
+            break;
+        case 'desk':
+            await runDeskHook();
+            break;
+        case 'install':
+            install();
+            break;
+        case 'uninstall':
+            uninstall();
+            break;
+        case 'status':
+            await status();
+            break;
+        default:
+            if (!runRuleCommand(arg, process.argv.slice(3)))
+                console.log(USAGE);
+    }
+}
+catch (e) {
+    // Never let a crash here block a tool call — see the note in index.ts.
+    if (!arg)
+        process.stdout.write('{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow"}}');
+    else
+        console.error(`agentpager-guard: ${e?.message ?? e}`);
+}
+process.exit(0);

package/dist/guard/cli.js

@@ -0,0 +1,174 @@
+// `agentpager guard rules | preset | allow | deny | ask | remove | budget | test`
+//
+// The point of this file is that setting a rule is one short command and trying it is another:
+//   agentpager guard deny "docker system prune"
+//   agentpager guard test "docker system prune"      → DENY, rule r1
+// Import-light like the hook itself: bin.ts loads it on every `agentpager-guard <verb>`.
+import { decide, presetModes } from './decide.js';
+import { commandOf } from './match.js';
+import { freeId, loadRules, patternError, PRESET_IDS, PRESETS, saveRules, validateRules, rulesPath, } from './rules.js';
+import { money, ZERO } from './spend.js';
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+export const USAGE = `Usage: agentpager guard <command>
+  install | uninstall | status         put the guard in / take it out of Claude Code
+  rules                                show every rule and what it does
+  preset <id> ask|deny|off             change a built-in rule (ids: ${PRESET_IDS.join(', ')})
+  ask|deny|allow "<pattern>"           add your own rule: plain text, or /regex/
+  remove <id>                          delete one of your rules
+  budget <usd> [--warn <fraction>]     per-session spend stop; 0 turns it off
+  test "<command>"                     dry run: which rule fires, and what happens
+  test --read <path>                   same, for the agent opening a file`;
+/** Splits `--flag value` pairs out of an argument list. */
+function flags(args) {
+    const words = [];
+    const out = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--'))
+            out[args[i].slice(2)] = args[++i] ?? '';
+        else
+            words.push(args[i]);
+    }
+    return { words, flags: out };
+}
+const badge = (d) => (d === 'deny' ? '\x1b[31mDENY\x1b[0m' : d === 'ask' ? '\x1b[33mASK\x1b[0m' : '\x1b[32mALLOW\x1b[0m');
+export function showRules() {
+    const r = loadRules();
+    const modes = presetModes(r);
+    console.log(`${bold('Guard rules')}  ${dim(rulesPath())}\n`);
+    console.log(`budget   ${r.budgetUsd > 0 ? `${money(r.budgetUsd)} per session, warns at ${money(r.budgetUsd * r.warnAt)}, stops at the limit` : 'off'}`);
+    console.log(`phone    ${r.phone === 'never' ? 'never asked — questions stay in the terminal' : `asked first (${r.phoneTimeoutSec}s), then the terminal`}\n`);
+    console.log(bold('Built-in rules'));
+    for (const p of PRESETS) {
+        console.log(`  ${p.id.padEnd(14)} ${modes[p.id].toUpperCase().padEnd(5)} ${p.title}  ${dim(`e.g. ${p.example}`)}`);
+    }
+    if (r.askOnDanger === false)
+        console.log(`  ${'always_ask'.padEnd(14)} OFF   sudo, git reset --hard, plain git push, mkfs … (askOnDanger:false)`);
+    console.log(`\n${bold('Your rules')} ${dim('(checked first, top to bottom)')}`);
+    if (!r.custom.length)
+        console.log(dim('  none — add one:  agentpager guard deny "docker system prune"'));
+    for (const c of r.custom)
+        console.log(`  ${c.id.padEnd(8)} ${c.action.toUpperCase().padEnd(5)} ${c.pattern}${c.note ? dim(`  — ${c.note}`) : ''}`);
+    console.log(dim('\nTry a command:  agentpager guard test "<command>"'));
+}
+function setPreset(id, mode) {
+    if (!id || !PRESET_IDS.includes(id) || !['ask', 'deny', 'off'].includes(mode ?? '')) {
+        console.error(`Usage: agentpager guard preset <id> ask|deny|off\n  ids: ${PRESET_IDS.join(', ')}`);
+        process.exitCode = 1;
+        return;
+    }
+    const r = loadRules();
+    r.presets[id] = mode;
+    saveRules(r);
+    const meta = PRESETS.find((p) => p.id === id);
+    console.log(`${id} → ${mode.toUpperCase()}  (${meta.title})`);
+    if (mode === 'off')
+        console.log(dim(`The guard will no longer look at things like: ${meta.example}`));
+}
+function addRule(action, args) {
+    const { words, flags: f } = flags(args);
+    const pattern = words.join(' ').trim();
+    const bad = patternError(pattern);
+    if (bad) {
+        console.error(`${bad}\nUsage: agentpager guard ${action} "<text or /regex/>" [--note "why"]`);
+        process.exitCode = 1;
+        return;
+    }
+    const r = loadRules();
+    const rule = { id: freeId(r), pattern, action, ...(f.note ? { note: f.note.slice(0, 200) } : {}) };
+    r.custom.push(rule);
+    const v = validateRules(r); // last line of defence: never write a file we would refuse to read
+    if (!v.ok) {
+        console.error(v.error);
+        process.exitCode = 1;
+        return;
+    }
+    saveRules(v.rules);
+    console.log(`${rule.id}: ${action.toUpperCase()} anything matching ${pattern}`);
+    console.log(dim(`Check it: agentpager guard test "${pattern.startsWith('/') ? '<a command>' : pattern}"   Remove it: agentpager guard remove ${rule.id}`));
+}
+function removeRule(id) {
+    const r = loadRules();
+    const before = r.custom.length;
+    r.custom = r.custom.filter((c) => c.id !== id);
+    if (r.custom.length === before) {
+        console.error(`No rule of yours has the id "${id ?? ''}". See them with: agentpager guard rules`);
+        process.exitCode = 1;
+        return;
+    }
+    saveRules(r);
+    console.log(`Removed ${id}.`);
+}
+function setBudget(args) {
+    const { words, flags: f } = flags(args);
+    const usd = Number(words[0]);
+    if (words[0] === undefined || !Number.isFinite(usd) || usd < 0) {
+        console.error('Usage: agentpager guard budget <usd> [--warn <fraction, e.g. 0.25>]   (0 turns the budget off)');
+        process.exitCode = 1;
+        return;
+    }
+    const r = loadRules();
+    r.budgetUsd = usd;
+    if (f.warn !== undefined)
+        r.warnAt = Number(f.warn);
+    const v = validateRules(r);
+    if (!v.ok) {
+        console.error(v.error);
+        process.exitCode = 1;
+        return;
+    }
+    saveRules(v.rules);
+    console.log(usd > 0 ? `Budget ${money(usd)} per session, warning at ${money(usd * v.rules.warnAt)}.` : 'Budget off.');
+}
+/** Dry run: exactly what the hook would decide, without running or asking anything. */
+export function testCommand(args) {
+    const { words, flags: f } = flags(args);
+    const read = f.read;
+    const text = words.join(' ').trim();
+    if (!read && !text) {
+        console.error('Usage: agentpager guard test "<command>"    or    agentpager guard test --read <path>');
+        process.exitCode = 1;
+        return;
+    }
+    const cfg = loadRules();
+    const tool = read ? 'Read' : 'Bash';
+    const input = read ? { file_path: read } : { command: text };
+    const r = decide(tool, input, ZERO, cfg);
+    console.log(`${dim(read ? 'Read' : '$')} ${read ?? commandOf(input)}`);
+    console.log(`${badge(r.decision)}${r.rule ? `  rule: ${r.rule}` : '  no rule matches'}`);
+    if (r.reason)
+        console.log(r.reason);
+    if (r.context)
+        console.log(dim(r.context));
+    if (r.decision === 'ask')
+        console.log(dim(`(with a phone paired, this question goes to the phone first; headless with no phone it is refused — see docs/GUARD_HEADLESS.md)`));
+    if (r.decision === 'allow' && !r.rule)
+        console.log(dim('Nothing stops this. To stop it: agentpager guard ask|deny "<text>"'));
+}
+/** Handles the rules-related verbs. Returns false for a verb it does not know. */
+export function runRuleCommand(verb, args) {
+    switch (verb) {
+        case 'rules':
+            showRules();
+            return true;
+        case 'preset':
+            setPreset(args[0], args[1]);
+            return true;
+        case 'ask':
+        case 'deny':
+        case 'allow':
+            addRule(verb, args);
+            return true;
+        case 'remove':
+            removeRule(args[0]);
+            return true;
+        case 'budget':
+            setBudget(args);
+            return true;
+        case 'test':
+            testCommand(args);
+            return true;
+        default:
+            return false;
+    }
+}

package/dist/guard/decide.js

@@ -0,0 +1,165 @@
+// The decision, with nothing else attached.
+//
+// Kept pure — in, out, no filesystem, no stdin, no clock — because this is the part that must be
+// right. Everything around it (reading the transcript, parsing the hook payload, writing JSON to
+// stdout) is plumbing that can be exercised separately.
+import { warning } from './explain.js';
+import { commandOf, DEFAULT_SAYS, presetsHit, residualDanger, subjectOf } from './match.js';
+import { compilePattern, defaultPresets, PRESET_IDS } from './rules.js';
+import { read as readLimits, whenBack, worstUsedPct, worstWindow } from './limits.js';
+import { money } from './spend.js';
+export const DEFAULTS = {
+    warnAt: 0.8,
+    askOnDanger: true,
+};
+/** The custom rules of a config, with legacy `denyPatterns` folded in after them. */
+export function customRulesOf(cfg) {
+    const legacy = (cfg.denyPatterns ?? []).map((p, i) => ({
+        id: `legacy${i + 1}`,
+        pattern: `/${p}/`,
+        action: 'deny',
+        note: 'from denyPatterns',
+    }));
+    return [...(cfg.custom ?? []), ...legacy];
+}
+/** Effective mode of every preset for a config (legacy askOnDanger:false with no presets = all off). */
+export function presetModes(cfg) {
+    const modes = defaultPresets();
+    if (cfg.askOnDanger === false && !cfg.presets)
+        for (const id of PRESET_IDS)
+            modes[id] = 'off';
+    for (const id of PRESET_IDS) {
+        const m = cfg.presets?.[id];
+        if (m === 'ask' || m === 'deny' || m === 'off')
+            modes[id] = m;
+    }
+    return modes;
+}
+const HOW = (id) => `Change it with: agentpager guard preset ${id} ask|deny|off`;
+/** The one place a tool call is judged. */
+export function decide(tool, input, spend, cfg) {
+    const command = commandOf(input);
+    const budget = cfg.budgetUsd ?? 0;
+    // 0 ── The plan window, which is what a subscriber actually runs out of.
+    //
+    // Checked before dollars because for most people dollars are a fiction: a Pro or Max plan buys
+    // five-hour and weekly windows, not tokens. The reading comes from limits.json, which the bridge
+    // writes when it sees rate_limits on the stream — the guard is a hook and cannot see that itself.
+    //
+    // A stale reading is IGNORED rather than enforced. Blocking somebody's work because of a number
+    // from yesterday is the one failure they would never forgive, and worstUsedPct returns null
+    // rather than a guess once the snapshot ages out.
+    const planCap = cfg.planCapPercent ?? 0;
+    if (planCap > 0) {
+        const snap = readLimits();
+        const used = worstUsedPct(snap);
+        if (used !== null && used >= planCap) {
+            const back = whenBack(snap);
+            const which = worstWindow(snap) === 'sevenDay' ? 'weekly' : '5-hour';
+            return {
+                decision: 'deny',
+                rule: 'plan-limit',
+                reason: `Plan limit reached: ${used}% of your ${which} allowance is used, and your cap is ${planCap}%. ` +
+                    (back ? `It resets ${back}. ` : '') +
+                    `Raise or remove planCapPercent in ~/.agentpager/guard.json to carry on.`,
+            };
+        }
+    }
+    // 1 ── The budget gate comes FIRST, and it denies rather than asks.
+    //
+    // Asking would be the polite thing and it is exactly the failure everyone has already lived
+    // through: a person who has approved 93% of prompts approves this one too, and the cap becomes a
+    // speed bump. #93255 is a user who set $20, was asked, kept tapping, and spent $40. A cap that can
+    // be tapped through is a display, not a cap.
+    if (budget > 0 && spend.usd >= budget) {
+        return {
+            decision: 'deny',
+            rule: 'budget',
+            reason: `Budget reached: this session has spent ${money(spend.usd)} of its ${money(budget)} limit, ` +
+                `so no further tool calls will run. Raise it with AGENTPAGER_BUDGET_USD, or edit ` +
+                `~/.agentpager/guard.json, then continue.`,
+        };
+    }
+    let verdict = null;
+    const subject = subjectOf(input);
+    const explained = command ? warning(command) : null;
+    // 2 ── Your own rules, first match wins. They run before presets so "allow" can exempt a command
+    // the presets would ask about, and "deny" can be stricter than any preset.
+    for (const rule of customRulesOf(cfg)) {
+        if (!subject || !compilePattern(rule.pattern)(subject))
+            continue;
+        const note = rule.note ? ` (${rule.note})` : '';
+        if (rule.action === 'allow') {
+            verdict = { decision: 'allow', rule: rule.id };
+        }
+        else if (rule.action === 'deny') {
+            verdict = {
+                decision: 'deny',
+                rule: rule.id,
+                reason: `Refused by your own rule ${rule.id} (${rule.pattern})${note}.${explained ? ` ${explained}` : ''}`,
+            };
+        }
+        else {
+            verdict = {
+                decision: 'ask',
+                rule: rule.id,
+                reason: `Your own rule ${rule.id} (${rule.pattern}) asks first${note}.${explained ? ` ${explained}` : ''}`,
+            };
+        }
+        break;
+    }
+    // 3 ── Presets: the worst-first list, each ask | deny | off.
+    if (!verdict) {
+        const modes = presetModes(cfg);
+        const hits = presetsHit(tool, input);
+        for (const { id, hit } of hits) {
+            const mode = modes[id];
+            if (mode === 'off')
+                continue;
+            const says = hit.says ?? explained ?? DEFAULT_SAYS[id];
+            verdict =
+                mode === 'deny'
+                    ? { decision: 'deny', rule: id, reason: `Blocked by rule ${id}: ${says} ${HOW(id)}` }
+                    : { decision: 'ask', rule: id, reason: `${says} (rule: ${id})` };
+            break;
+        }
+        // 4 ── Anything else irreversible still stops for a human — unless a preset owns the command
+        // (then "off" means off).
+        if (!verdict && !hits.length && command && (cfg.askOnDanger ?? DEFAULTS.askOnDanger)) {
+            const says = residualDanger(command);
+            if (says)
+                verdict = { decision: 'ask', rule: 'always_ask', reason: `${explained ?? says} (rule: always_ask)` };
+        }
+    }
+    if (verdict && verdict.decision !== 'allow')
+        return verdict;
+    // 5 ── Approaching the budget is worth saying once, to the model, without blocking anything.
+    //
+    // The model is the only party that can actually act on it — it can pick a cheaper path, stop
+    // fanning out subagents, or finish early. Telling the human at 80% just makes them anxious at a
+    // moment when they cannot do anything useful.
+    const warnAt = cfg.warnAt ?? DEFAULTS.warnAt;
+    if (budget > 0 && spend.usd >= budget * warnAt) {
+        const left = Math.max(0, budget - spend.usd);
+        return {
+            decision: 'allow',
+            ...(verdict?.rule ? { rule: verdict.rule } : {}),
+            context: `Budget notice: ${money(spend.usd)} of ${money(budget)} spent, ${money(left)} left. ` +
+                `Prefer cheaper models and avoid spawning parallel subagents; work will be blocked at the limit.`,
+        };
+    }
+    return verdict ?? { decision: 'allow' };
+}
+/** The exact envelope Claude Code expects back on stdout for a PreToolUse hook. */
+export function hookOutput(r) {
+    const out = {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: r.decision,
+            ...(r.reason ? { permissionDecisionReason: r.reason } : {}),
+        },
+    };
+    if (r.context)
+        out.hookSpecificOutput = { ...out.hookSpecificOutput, additionalContext: r.context };
+    return JSON.stringify(out);
+}

package/dist/guard/desk.js

@@ -0,0 +1,63 @@
+// The desk lock: "you are working in this session on the computer right now".
+//
+// Two processes writing one Claude session transcript corrupt each other — and the phone resuming a
+// session while you are typing into it at the desk is exactly that. So every guard invocation at the
+// desk leaves a heartbeat, `~/.agentpager/desk/<session_id>` (its mtime is the timestamp), and the
+// bridge refuses a phone `prompt` for a session whose heartbeat is fresh.
+//
+// A session with NO heartbeat is never affected: no guard installed, or nobody at the desk.
+// Import-light: node builtins + rules.ts only (this runs on every tool call).
+import { mkdirSync, readdirSync, rmSync, statSync, utimesSync, closeSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentpagerHome } from './rules.js';
+/** How recent a heartbeat must be to count as "active at the desk". */
+export const DESK_FRESH_MS = 20_000;
+const SAFE_ID = /^[\w-]{8,80}$/;
+export const deskDir = () => join(agentpagerHome(), 'desk');
+/** Records that the desk is active in this session right now. Never throws. */
+export function touchDesk(sessionId) {
+    if (typeof sessionId !== 'string' || !SAFE_ID.test(sessionId))
+        return;
+    try {
+        mkdirSync(deskDir(), { recursive: true, mode: 0o700 });
+        const p = join(deskDir(), sessionId);
+        const now = new Date();
+        try {
+            utimesSync(p, now, now);
+        }
+        catch {
+            closeSync(openSync(p, 'a', 0o600)); // first time: create it
+        }
+    }
+    catch {
+        /* a broken heartbeat must never break the guard */
+    }
+}
+/** Milliseconds since the desk was last active in this session, or null when it never was. */
+export function deskAgeMs(sessionId, now = Date.now()) {
+    if (!SAFE_ID.test(sessionId))
+        return null;
+    try {
+        return now - statSync(join(deskDir(), sessionId)).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+export const deskActive = (sessionId, now = Date.now()) => {
+    const age = deskAgeMs(sessionId, now);
+    return age !== null && age < DESK_FRESH_MS;
+};
+/** Heartbeats are empty files, one per session ever touched: sweep the old ones. */
+export function pruneDesk(maxAgeMs = 7 * 24 * 3600_000) {
+    try {
+        for (const f of readdirSync(deskDir())) {
+            const p = join(deskDir(), f);
+            if (Date.now() - statSync(p).mtimeMs > maxAgeMs)
+                rmSync(p, { force: true });
+        }
+    }
+    catch {
+        /* nothing to sweep */
+    }
+}

package/dist/guard/explain.js

@@ -0,0 +1,49 @@
+// Say what the command will DO, not what it says.
+//
+// Claude Code issue #30505 asked for exactly this — "the prompt only displays the raw command, which
+// requires technical knowledge to evaluate… `rm -rf /` → ⚠️ This command will permanently delete
+// files and cannot be undone" — and was closed "not planned". It was filed because, as agents reach
+// people who are not engineers, a raw shell string is not information. The lawyer in #95637 said the
+// same thing from the other side: "I am a lawyer, not a software engineer; I rely on Claude Code for
+// exactly these decisions."
+//
+// It also matters for people who ARE engineers, because of approval fatigue: Anthropic's own
+// telemetry says users approve 93% of prompts. A wall of identical-looking commands is what trains
+// someone to tap Allow without reading, and then to reach for --dangerously-skip-permissions.
+// A sentence that is different when the stakes are different is the only thing that survives that.
+const RULES = [
+    { re: /\brm\s+(-[a-z]*[rf]|--recursive|--force)/i, says: 'deletes files permanently — there is no undo and no Trash', permanent: true },
+    { re: /\bgit\s+push\b[^|;&]*\s(--force|-f)\b|\bgit\s+push\s+--force/i, says: 'overwrites the remote history — commits on the server can be lost for everyone', permanent: true },
+    { re: /\bgit\s+reset\s+--hard\b/i, says: 'throws away uncommitted work in this repository', permanent: true },
+    { re: /\bgit\s+clean\s+-[a-z]*f/i, says: 'deletes untracked files, including ones git has never seen', permanent: true },
+    { re: /\bgit\s+branch\s+-D\b/i, says: 'force-deletes a branch even if it was never merged' },
+    { re: /\bgit\s+push\b/i, says: 'publishes commits to the shared remote where other people will pull them' },
+    { re: /\bdrop\s+(table|database)\b|\btruncate\s+table\b/i, says: 'destroys database data permanently', permanent: true },
+    { re: /\b(mkfs|dd\s+if=)/i, says: 'writes directly to a disk and can destroy the whole filesystem', permanent: true },
+    { re: /\b(shutdown|reboot)\b/i, says: 'shuts down or restarts this machine' },
+    { re: /\b(curl|wget)\b[^|]*\|\s*(sudo\s+)?(ba|z)?sh\b/i, says: 'downloads a script from the internet and runs it immediately, unread' },
+    { re: /\bsudo\b/i, says: 'runs with administrator rights, so it is not limited to your own files' },
+    { re: /\bchmod\s+-R\b|\bchown\s+-R\b/i, says: 'changes permissions or ownership across a whole directory tree' },
+    { re: /\bdocker\s+(system\s+prune|volume\s+rm)\b/i, says: 'removes Docker data, including volumes that may hold the only copy of something', permanent: true },
+    { re: /\bkubectl\s+delete\b|\bterraform\s+destroy\b/i, says: 'tears down live infrastructure', permanent: true },
+    { re: /\bterraform\s+apply\b|\bkubectl\s+apply\b/i, says: 'changes live infrastructure' },
+    { re: /\b(npm|pnpm|yarn|cargo|twine|gem)\s+publish\b/i, says: 'publishes a package publicly — versions cannot be unpublished cleanly', permanent: true },
+    { re: /\bgh\s+repo\s+delete\b/i, says: 'deletes a GitHub repository', permanent: true },
+    { re: /\bgh\s+(release|pr\s+merge)\b/i, says: 'changes the public state of the repository' },
+    { re: /\b(firebase|vercel|netlify|fly|heroku)\s+deploy\b|\bdeploy\b/i, says: 'deploys to a live environment that real users can reach' },
+];
+export function explain(command) {
+    const hits = RULES.filter((r) => r.re.test(command));
+    if (!hits.length)
+        return { says: null, permanent: false };
+    // Rules are ordered worst-first, so the first match is the one worth saying out loud. Listing all
+    // of them turns a warning back into a wall of text, which is the problem we are solving.
+    return { says: hits[0].says, permanent: hits.some((h) => h.permanent === true) };
+}
+/** The full line a person reads before deciding. */
+export function warning(command) {
+    const { says, permanent } = explain(command);
+    if (!says)
+        return null;
+    return permanent ? `This ${says}. It cannot be undone.` : `This ${says}.`;
+}