@pushary/agent-hooks 0.28.2 → 0.29.0

package/README.md

@@ -22,7 +22,7 @@ There are three things.
 
 **Ask.** The agent asks you questions through push: yes/no, multiple choice, or free text. It waits for your answer. When Pushary is connected, the agent sends its questions to your phone instead of stalling in the terminal.
 
-**Gate.** Risky shell commands (`rm -rf`, force pushes, history rewrites, database drops, deploys) are checked before they run. What happens is set by your dashboard policy: auto approve trusted read-only commands, push to your phone for approval, or hold for the phone and never auto-deny. If the check cannot run, the command is blocked instead of allowed. It fails closed.
+**Gate.** Risky shell commands (`rm -rf`, force pushes, history rewrites, database drops, deploys) are checked before they run. What happens is set by your dashboard policy: auto approve trusted read-only commands, push to your phone for approval, or hold for the phone and never auto-deny. If the check cannot run, the decision falls back to the agent's own permission prompt in the terminal; nothing is silently allowed. Without an API key configured, the hooks stay out of the way entirely and only count what they would have gated.
 
 ## Setup
 
@@ -62,8 +62,10 @@ Any other MCP client can use notify and ask by pointing at the Pushary MCP endpo
 setup    Configure Claude Code, Codex, Gemini CLI, Hermes, or Cursor with Pushary
 doctor   Verify your Pushary installation is working
 clean    Remove all Pushary configuration
-mode     Switch approval mode (push_only, push_first, terminal_only)
+mode     Switch approval mode (push_only, push_first, terminal_only, notify_only)
 wait     Show or set the "wait for your phone" ladder (pushary wait 45)
+stats    Show the approval moments your agents hit while not connected
+upgrade  Update the globally installed hooks to the latest version
 hook     Run as a PreToolUse hook (reads stdin, writes stdout)
 ```
 
@@ -97,7 +99,7 @@ The MCP server exposes `send_notification`, `ask_user`, `wait_for_answer`, and `
 
 ## Security
 
-The permission gate fails closed. If a policy cannot be fetched or a hook errors, the command is blocked, not allowed. Secrets in command arguments and environment are redacted before anything is sent to a phone or stored. Read-only commands can be allowlisted so trusted work never interrupts you, while writes and destructive commands still route through approval.
+If a policy cannot be fetched or a hook errors, the decision falls back to the agent's native permission prompt, never a silent allow. The Cursor gate is the strictest surface: it blocks matched risky commands outright when its check cannot run. Secrets in command arguments and environment are redacted before anything is sent to a phone or stored. Read-only commands can be allowlisted so trusted work never interrupts you, while writes and destructive commands still route through approval.
 
 ## Links
 

package/dist/bin/pushary-clean.js

@@ -4,11 +4,13 @@ import {
   removePusharySettings
 } from "../chunk-QNEYHDKR.js";
 import {
-  execNpm,
   removeCodexHooks,
   removeGeminiSettings,
   removeInstructionBlock
-} from "../chunk-X3YCHQQK.js";
+} from "../chunk-XY6OKUQ4.js";
+import {
+  execNpm
+} from "../chunk-RSHN2AQ7.js";
 import "../chunk-Z5PL3K7C.js";
 
 // bin/pushary-clean.ts

package/dist/bin/pushary-doctor.js

@@ -4,7 +4,6 @@ import {
 } from "../chunk-IIENZE2J.js";
 import {
   GEMINI_HOOK_BINARY,
-  execNpm,
   hasCodexHooks,
   hasGeminiHooks,
   hasInstructionBlock,
@@ -12,7 +11,10 @@ import {
   missingGeminiHookEvents,
   readCodexMcpAuth,
   untrustedCodexHookEvents
-} from "../chunk-X3YCHQQK.js";
+} from "../chunk-XY6OKUQ4.js";
+import {
+  execNpm
+} from "../chunk-RSHN2AQ7.js";
 import {
   callMcpTool,
   sendMcpRequest

package/dist/bin/pushary-hook.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   handlePreToolUse
-} from "../chunk-P6QBZS27.js";
+} from "../chunk-GPLKEAFG.js";
+import "../chunk-WLF3NCHS.js";
 import "../chunk-KQYIHZ5E.js";
 import "../chunk-IAOXM7X5.js";
 import "../chunk-DWED7BS3.js";
@@ -28,7 +29,7 @@ var main = async () => {
   }
   try {
     const output = await handlePreToolUse(input);
-    process.stdout.write(JSON.stringify(output));
+    if (output) process.stdout.write(JSON.stringify(output));
   } catch (err) {
     process.stderr.write(
       `[pushary-hook] Error: ${err instanceof Error ? err.message : String(err)}

package/dist/bin/pushary-setup.js

@@ -11,12 +11,14 @@ import {
   addCodexMcpServer,
   addGeminiHooks,
   addGeminiMcpServer,
-  execNpm,
-  npmErrorMessage,
   renderAgentInstructions,
   renderProjectAgentInstructions,
   writeInstructionBlock
-} from "../chunk-X3YCHQQK.js";
+} from "../chunk-XY6OKUQ4.js";
+import {
+  execNpm,
+  npmErrorMessage
+} from "../chunk-RSHN2AQ7.js";
 import {
   reportEvent
 } from "../chunk-IAOXM7X5.js";
@@ -411,7 +413,7 @@ var checkForUpdates = async (current) => {
     const latest = data.version;
     if (latest && latest !== current) {
       console.log(`  ${yellow2("!")} Update available: ${dim2(current)} \u2192 ${green2(latest)}`);
-      console.log(`  ${dim2("Run:")} npx @pushary/agent-hooks@${latest} setup`);
+      console.log(`  ${dim2("Run:")} npx @pushary/agent-hooks@latest upgrade`);
       console.log();
     }
   } catch {

package/dist/bin/pushary-stats.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/pushary-stats.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import {
+  readLedgerSummary
+} from "../chunk-WLF3NCHS.js";
+import "../chunk-Z5PL3K7C.js";
+import {
+  getApiKey
+} from "../chunk-NKXSILEW.js";
+
+// bin/pushary-stats.ts
+var DAYS = 7;
+var summary = readLedgerSummary(DAYS);
+var connected = true;
+try {
+  getApiKey();
+} catch {
+  connected = false;
+}
+var plural = (count, word) => count === 1 ? word : `${word}s`;
+if (summary.count === 0) {
+  if (connected) {
+    console.log("No locally counted approval moments in the last 7 days. Connected sessions land in your dashboard: https://pushary.com/dashboard/agent/activity");
+  } else {
+    console.log("No approval moments counted yet. Run your agent with the Pushary hooks installed and check back after a session or two.");
+  }
+  process.exit(0);
+}
+var toolLines = Object.entries(summary.byTool).sort((a, b) => b[1] - a[1]).map(([tool, count]) => `  ${tool}: ${count}`).join("\n");
+console.log(`In the last ${DAYS} days, your agents hit ${summary.count} approval ${plural(summary.count, "moment")} across ${summary.sessions} ${plural(summary.sessions, "session")} while Pushary was not connected:
+`);
+console.log(toolLines);
+console.log();
+if (connected) {
+  console.log("A key is configured now, so new moments reach your phone instead of waiting in the terminal.");
+} else {
+  console.log("Each of those sat in the terminal until you noticed. With Pushary they land on your lock screen as a yes or no.");
+  console.log("7-day trial: https://pushary.com/sign-up?utm_source=cli&utm_medium=stats");
+}

package/dist/bin/pushary-upgrade.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin/pushary-upgrade.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import {
+  execNpm,
+  npmErrorMessage
+} from "../chunk-RSHN2AQ7.js";
+
+// bin/pushary-upgrade.ts
+var getInstalledVersion = () => {
+  try {
+    return execNpm("list -g --no-workspaces @pushary/agent-hooks --depth=0", { timeout: 1e4 }).toString().match(/@pushary\/agent-hooks@([\d.]+)/)?.[1] ?? "";
+  } catch {
+    return "";
+  }
+};
+var fetchLatestVersion = async () => {
+  try {
+    const res = await fetch("https://registry.npmjs.org/@pushary/agent-hooks/latest", {
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!res.ok) return void 0;
+    const data = await res.json();
+    return data.version;
+  } catch {
+    return void 0;
+  }
+};
+var isNewer = (a, b) => {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) > (pb[i] ?? 0)) return true;
+    if ((pa[i] ?? 0) < (pb[i] ?? 0)) return false;
+  }
+  return false;
+};
+var main = async () => {
+  const installed = getInstalledVersion();
+  if (!installed) {
+    console.log("No global install of @pushary/agent-hooks found, so there is nothing to upgrade.");
+    console.log("Plugin installs update on their own. To set up the CLI hooks: npx @pushary/agent-hooks@latest setup");
+    return;
+  }
+  const latest = await fetchLatestVersion();
+  if (latest && !isNewer(latest, installed)) {
+    console.log(`Already on the latest version (${installed}).`);
+    return;
+  }
+  console.log(`Upgrading @pushary/agent-hooks ${installed} -> ${latest ?? "latest"}`);
+  try {
+    execNpm("install -g --no-workspaces @pushary/agent-hooks@latest", { timeout: 12e4 });
+  } catch (err) {
+    console.error(`Upgrade failed: ${npmErrorMessage(err)}`);
+    process.exit(1);
+  }
+  console.log("Done. Your hooks point at the global install, so agents pick this up on their next tool call.");
+  console.log("Verify with: pushary doctor");
+};
+main();

package/dist/bin/pushary.js

@@ -14,6 +14,10 @@ if (command === "setup") {
   await import("./pushary-mode.js");
 } else if (command === "wait") {
   await import("./pushary-wait.js");
+} else if (command === "stats") {
+  await import("./pushary-stats.js");
+} else if (command === "upgrade") {
+  await import("./pushary-upgrade.js");
 } else {
   console.log(`
 Pushary Agent Hooks
@@ -24,6 +28,8 @@ Commands:
   clean    Remove all Pushary configuration
   mode     Switch approval mode (push_only, push_first, terminal_only)
   wait     Show or set the "wait for your phone" ladder (pushary wait 45)
+  stats    Show the approval moments your agents hit while not connected
+  upgrade  Update the globally installed hooks to the latest version
   hook     Run as a PreToolUse hook (reads stdin, writes stdout)
 
 Setup options:

package/dist/{chunk-P6QBZS27.js → chunk-GPLKEAFG.js}

@@ -1,3 +1,7 @@
+import {
+  isGatingMoment,
+  recordKeylessMoment
+} from "./chunk-WLF3NCHS.js";
 import {
   denyReasonFrom,
   isDeferAnswer
@@ -31,7 +35,9 @@ import {
 } from "./chunk-NKXSILEW.js";
 
 // src/hook.ts
-import { basename } from "path";
+import { basename, join } from "path";
+import { tmpdir } from "os";
+import { existsSync, writeFileSync } from "fs";
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var START_MS = Date.now();
 var allow = () => ({
@@ -182,9 +188,41 @@ var handleNotifyOnly = async (apiKey, description, projectName, sessionId, machi
   }
   return ask();
 };
+var KEYLESS_NOTICE = "[pushary] Not connected (no API key), so your agent runs untouched. Approval moments are counted locally; see them with: npx @pushary/agent-hooks@latest stats. Connect: https://pushary.com/sign-up?utm_source=cli&utm_medium=keyless-hook";
+var keylessNoticeOnce = (sessionId) => {
+  try {
+    const key = (sessionId || DEFAULT_SESSION).replace(/[^a-zA-Z0-9_-]/g, "");
+    const marker = join(tmpdir(), `pushary-keyless-${key}`);
+    if (existsSync(marker)) return;
+    writeFileSync(marker, "1", "utf-8");
+    process.stderr.write(`${KEYLESS_NOTICE}
+`);
+  } catch {
+  }
+};
+var handleKeyless = (input) => {
+  try {
+    if (isGatingMoment(input.tool_name, input.tool_input ?? {})) {
+      recordKeylessMoment({
+        ts: Date.now(),
+        tool: input.tool_name,
+        project: basename(input.cwd ?? process.cwd()),
+        sessionId: input.session_id
+      });
+    }
+    keylessNoticeOnce(input.session_id);
+  } catch {
+  }
+  return void 0;
+};
 var handlePreToolUse = async (input) => {
+  let apiKey;
+  try {
+    apiKey = getApiKey();
+  } catch {
+    return handleKeyless(input);
+  }
   try {
-    const apiKey = getApiKey();
     const modeState = await fetchModeState(apiKey, input.session_id);
     const policy = await getPolicy(apiKey, modeState.policyVersion);
     if (modeState.kill) {

package/dist/chunk-RSHN2AQ7.js

@@ -0,0 +1,29 @@
+// src/npm.ts
+import { execSync } from "child_process";
+var cleanNpmEnv = () => {
+  const env = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.toLowerCase().startsWith("npm_config_workspace")) continue;
+    env[key] = value;
+  }
+  return env;
+};
+var npmErrorMessage = (err) => {
+  const e = err;
+  const text = [e?.stderr, e?.stdout].map((part) => part ? part.toString() : "").join("\n");
+  const line = text.split("\n").map((l) => l.replace(/^npm error\s*/i, "").trim()).find((l) => l && !l.startsWith("A complete log") && !/^code\s/i.test(l));
+  return line || e?.message || String(err);
+};
+var execNpm = (args, options = {}) => {
+  return execSync(`npm ${args}`, {
+    timeout: 12e4,
+    stdio: "pipe",
+    ...options,
+    env: { ...cleanNpmEnv(), ...options.env ?? {} }
+  });
+};
+
+export {
+  npmErrorMessage,
+  execNpm
+};

package/dist/chunk-WLF3NCHS.js

@@ -0,0 +1,62 @@
+import {
+  isSafeReadOnlyCommand
+} from "./chunk-Z5PL3K7C.js";
+
+// src/ledger.ts
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from "fs";
+import { join, dirname } from "path";
+import { homedir } from "os";
+var ledgerPath = () => process.env.PUSHARY_LEDGER_FILE?.trim() || join(homedir(), ".pushary", "local-ledger.jsonl");
+var MAX_LEDGER_BYTES = 1e6;
+var isGatingMoment = (toolName, toolInput) => {
+  const command = typeof toolInput?.command === "string" ? toolInput.command : void 0;
+  if (toolName === "Bash" && command && isSafeReadOnlyCommand(command)) return false;
+  return true;
+};
+var recordKeylessMoment = (entry) => {
+  try {
+    const path = ledgerPath();
+    const dir = dirname(path);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (existsSync(path) && statSync(path).size > MAX_LEDGER_BYTES) {
+      rmSync(`${path}.1`, { force: true });
+      renameSync(path, `${path}.1`);
+    }
+    appendFileSync(path, `${JSON.stringify(entry)}
+`, "utf-8");
+  } catch {
+  }
+};
+var readLedgerSummary = (days = 7) => {
+  const sinceMs = Date.now() - days * 864e5;
+  const summary = { count: 0, sessions: 0, byTool: {}, sinceMs };
+  let raw;
+  try {
+    raw = readFileSync(ledgerPath(), "utf-8");
+  } catch {
+    return summary;
+  }
+  const sessions = /* @__PURE__ */ new Set();
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof entry.ts !== "number" || entry.ts < sinceMs) continue;
+    summary.count += 1;
+    const tool = typeof entry.tool === "string" && entry.tool ? entry.tool : "Other";
+    summary.byTool[tool] = (summary.byTool[tool] ?? 0) + 1;
+    sessions.add(entry.sessionId || `${entry.project ?? "unknown"}:no-session`);
+  }
+  summary.sessions = sessions.size;
+  return summary;
+};
+
+export {
+  isGatingMoment,
+  recordKeylessMoment,
+  readLedgerSummary
+};

package/dist/{chunk-X3YCHQQK.js → chunk-XY6OKUQ4.js}

@@ -307,31 +307,6 @@ var hasInstructionBlock = (filePath) => {
   }
 };
 
-// src/npm.ts
-import { execSync } from "child_process";
-var cleanNpmEnv = () => {
-  const env = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (key.toLowerCase().startsWith("npm_config_workspace")) continue;
-    env[key] = value;
-  }
-  return env;
-};
-var npmErrorMessage = (err) => {
-  const e = err;
-  const text = [e?.stderr, e?.stdout].map((part) => part ? part.toString() : "").join("\n");
-  const line = text.split("\n").map((l) => l.replace(/^npm error\s*/i, "").trim()).find((l) => l && !l.startsWith("A complete log") && !/^code\s/i.test(l));
-  return line || e?.message || String(err);
-};
-var execNpm = (args, options = {}) => {
-  return execSync(`npm ${args}`, {
-    timeout: 12e4,
-    stdio: "pipe",
-    ...options,
-    env: { ...cleanNpmEnv(), ...options.env ?? {} }
-  });
-};
-
 export {
   addCodexMcpServer,
   readCodexMcpAuth,
@@ -351,7 +326,5 @@ export {
   renderProjectAgentInstructions,
   writeInstructionBlock,
   removeInstructionBlock,
-  hasInstructionBlock,
-  npmErrorMessage,
-  execNpm
+  hasInstructionBlock
 };

package/dist/src/index.d.ts

@@ -15,7 +15,7 @@ interface HookOutput {
         permissionDecisionReason?: string;
     };
 }
-declare const handlePreToolUse: (input: ToolInput) => Promise<HookOutput>;
+declare const handlePreToolUse: (input: ToolInput) => Promise<HookOutput | undefined>;
 
 type ReceiptKind = 'edit' | 'write' | 'bash' | 'commit';
 interface ReceiptMeta {

package/dist/src/index.js

@@ -1,6 +1,7 @@
 import {
   handlePreToolUse
-} from "../chunk-P6QBZS27.js";
+} from "../chunk-GPLKEAFG.js";
+import "../chunk-WLF3NCHS.js";
 import "../chunk-KQYIHZ5E.js";
 import {
   askUser,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/agent-hooks",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Permission hooks for AI coding agents: route tool approvals through Pushary push notifications",
   "keywords": [
     "pushary",
@@ -54,7 +54,9 @@
     "pushary-clean": "./dist/bin/pushary-clean.js",
     "pushary-doctor": "./dist/bin/pushary-doctor.js",
     "pushary-mode": "./dist/bin/pushary-mode.js",
-    "pushary-wait": "./dist/bin/pushary-wait.js"
+    "pushary-wait": "./dist/bin/pushary-wait.js",
+    "pushary-stats": "./dist/bin/pushary-stats.js",
+    "pushary-upgrade": "./dist/bin/pushary-upgrade.js"
   },
   "files": [
     "dist",
@@ -63,7 +65,7 @@
   "scripts": {
     "build": "node scripts/bundle-plugin.mjs && tsup",
     "dev": "tsup --watch",
-    "test": "bun test src/api.test.ts && bun test src/claude-config.test.ts && bun test src/config.test.ts && bun test src/mcp-http.test.ts && bun test src/retry.test.ts && bun test src/usage.test.ts && bun test src/validate.test.ts && bun test src/policy.test.ts && bun test src/npm.test.ts && bun test src/identity.test.ts && bun test src/pending.test.ts && bun test src/events.test.ts && bun test src/describe.test.ts && bun test src/suggestions.test.ts && bun test src/safe-commands.test.ts && bun test src/hook.test.ts && bun test src/codex-adapter.test.ts && bun test src/codex-config.test.ts && bun test src/gemini-adapter.test.ts && bun test src/gemini-config.test.ts && bun test src/instruction-file.test.ts && bun test src/pairing.test.ts && bun test src/wait-ladder.test.ts"
+    "test": "bun test src/api.test.ts && bun test src/claude-config.test.ts && bun test src/config.test.ts && bun test src/mcp-http.test.ts && bun test src/retry.test.ts && bun test src/usage.test.ts && bun test src/validate.test.ts && bun test src/policy.test.ts && bun test src/npm.test.ts && bun test src/identity.test.ts && bun test src/pending.test.ts && bun test src/events.test.ts && bun test src/describe.test.ts && bun test src/suggestions.test.ts && bun test src/safe-commands.test.ts && bun test src/hook.test.ts && bun test src/codex-adapter.test.ts && bun test src/codex-config.test.ts && bun test src/gemini-adapter.test.ts && bun test src/gemini-config.test.ts && bun test src/instruction-file.test.ts && bun test src/pairing.test.ts && bun test src/wait-ladder.test.ts && bun test src/ledger.test.ts"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",