@pushary/agent-hooks 0.11.1 → 0.13.0

package/data/cursor-plugin/.cursor-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "pushary",
+  "displayName": "Pushary — Control Panel for AI Agents",
+  "description": "Push notifications, human-in-the-loop questions, and permission gating for your AI coding agent. Get a push when a task finishes, answer the agent from your phone, and approve risky commands before they run.",
+  "version": "0.1.0",
+  "author": { "name": "Pushary", "email": "business@pushary.com" },
+  "homepage": "https://pushary.com",
+  "repository": "https://github.com/Pushary/cursor-plugin",
+  "license": "MIT",
+  "keywords": [
+    "notifications",
+    "push",
+    "human-in-the-loop",
+    "permissions",
+    "approvals",
+    "mcp",
+    "agent",
+    "control-panel",
+    "ask",
+    "alerts"
+  ],
+  "category": "developer-tools",
+  "tags": ["notifications", "approvals", "human-in-the-loop", "mcp", "workflow"],
+  "logo": "assets/logo.png"
+}

package/data/cursor-plugin/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- MCP server (`send_notification`, `ask_user`, `wait_for_answer`, `cancel_question`) wired via `mcp.json`, key supplied at runtime through `PUSHARY_API_KEY`.
+- Always-on rule and full tool-reference skill so the agent uses Pushary proactively.
+- `beforeShellExecution` gate (`scripts/pushary-gate.mjs`, zero-dependency) that evaluates risky commands against your Pushary dashboard policy — auto-approve, the four approval modes, timeout actions, live mode override, and kill switch, scoped to the Cursor conversation. Falls back to Cursor's own prompt when Pushary is unreachable, and is fail-closed: a broken gate blocks rather than allows.
+- Commands: `/pushary-test`, `/notify-when-done`.

package/data/cursor-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pushary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/data/cursor-plugin/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Pushary" width="72" height="72" />
+</p>
+
+<h1 align="center">Pushary for Cursor</h1>
+
+<p align="center">A control panel for your AI coding agent. Get a push when work finishes, answer the agent from your phone, and approve risky commands before they run.</p>
+
+---
+
+## What it is
+
+Pushary connects Cursor to your phone. When the agent finishes a task, needs a decision, or is about to run something risky, it reaches you with a push notification. You answer from the lock screen and the agent keeps going. It works even when you have stepped away from your computer.
+
+## What it does
+
+There are three things.
+
+1. Notify. The agent sends a push when a long task finishes, or when a build, test, or deploy fails. The push can include what changed, the error, and suggested next steps.
+
+2. Ask. The agent asks you questions through push: yes or 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 waiting in the editor.
+
+3. Gate. Risky shell commands (like rm, force push, history rewrites, database drops, deploys, and systemctl) are checked before they run. What happens is set by your Pushary dashboard policy: auto approve trusted commands, push to your phone for approval, or just notify. If you do not answer in time, it falls back to Cursor's own prompt, so nothing dangerous runs silently. If the check cannot run at all, the command is blocked instead of allowed.
+
+## Install
+
+You need two things: the plugin, and an API key.
+
+### Option 1: Cursor Marketplace (recommended)
+
+Open the Marketplace panel in Cursor, search for Pushary, and click install. Then set your API key (see below).
+
+### Option 2: CLI
+
+This also sets up Claude Code, Codex, and Hermes if you use them.
+
+```bash
+npx @pushary/agent-hooks@latest setup
+```
+
+### Option 3: Manual MCP
+
+Add this to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:
+
+```json
+{
+  "mcpServers": {
+    "pushary": {
+      "type": "http",
+      "url": "https://pushary.com/api/mcp/mcp",
+      "headers": { "Authorization": "Bearer ${PUSHARY_API_KEY}" }
+    }
+  }
+}
+```
+
+However you install it, Pushary talks to the same server, so the plugin and the CLI give you the same setup.
+
+## Set your API key
+
+The plugin reads your key from the `PUSHARY_API_KEY` environment variable. Get a key at https://pushary.com, then add it to your shell profile:
+
+```bash
+echo 'export PUSHARY_API_KEY="pk_xxx.sk_xxx"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Install the Pushary app on your phone (or turn on web push) so the agent can reach you.
+
+## What is in the plugin
+
+| Part | File | What it does |
+|------|------|--------------|
+| MCP server | `mcp.json` | Connects Cursor to the Pushary tools: `send_notification`, `ask_user`, `wait_for_answer`, `cancel_question` |
+| Rule | `rules/pushary.mdc` | Always on guidance so the agent uses Pushary on its own |
+| Skill | `skills/pushary/SKILL.md` | Full tool reference: parameters, examples, return values |
+| Hook | `hooks/hooks.json` and `scripts/pushary-gate.mjs` | Sends risky commands to your phone for approval |
+| Commands | `commands/` | `/pushary-test` and `/notify-when-done` |
+
+## How the gate decides
+
+There are two layers.
+
+1. The matcher in `hooks/hooks.json` is a list of patterns that decides which commands get checked at all. Edit it to add or remove patterns.
+
+2. Your Pushary dashboard policy decides what happens to a checked command, per tool: auto approve, the approval mode (push and wait, push then prompt, notify only, or prompt only), the timeout action, a live mode override, and the kill switch. This is the same policy your other Pushary agents use, so the behavior stays the same across agents.
+
+## Commands
+
+- `/pushary-test` sends a test push so you can confirm delivery.
+- `/notify-when-done` tells the agent to push a summary when the current task finishes.
+
+## Development
+
+`skills/pushary/SKILL.md` mirrors the Pushary skill that ships with `@pushary/agent-hooks`. Keep the two the same.
+
+Test the plugin locally before publishing:
+
+```bash
+ln -s "$(pwd)" ~/.cursor/plugins/local/pushary
+```
+
+Then reload Cursor with Developer: Reload Window.
+
+## Security
+
+This repository has no secrets. Your key is read at runtime from `PUSHARY_API_KEY`. The gate script has no dependencies and only talks to pushary.com. Read `scripts/pushary-gate.mjs` to see exactly what it sends. See `SECURITY.md` for details.
+
+## License
+
+MIT. See `LICENSE`.

package/data/cursor-plugin/SECURITY.md

@@ -0,0 +1,33 @@
+# Security
+
+## Reporting a vulnerability
+
+Email **security@pushary.com** with details and reproduction steps. Please do not open a public
+issue for security reports. We aim to acknowledge within 72 hours.
+
+## What this plugin sends
+
+The plugin connects Cursor to the Pushary MCP server at `https://pushary.com/api/mcp/mcp` using
+the API key you provide via the `PUSHARY_API_KEY` environment variable. No key is committed to
+this repository.
+
+The permission gate (`scripts/pushary-gate.mjs`) runs only on shell commands matching the regex
+in `hooks/hooks.json`. For a matched command it sends, over HTTPS to Pushary:
+
+- the command text,
+- the basename of the working directory (e.g. `my-repo`, not the full path),
+- an agent label (`Cursor - <project>`),
+- the Cursor conversation id, so the dashboard kill switch and per-session mode can target this session,
+- a machine id — the first 8 hex characters of a SHA-256 of your hostname (never the hostname itself).
+
+It also fetches your permission policy and mode from `pushary.com` (the policy is cached in the
+system temp directory for 5 minutes). It contacts no host other than `pushary.com`, has no
+third-party dependencies, and writes only that policy cache to disk. The full source is in this
+repository — read it before installing.
+
+## Fail-closed by design
+
+The gate is configured `failClosed: true`. If the gate cannot produce a decision (crash,
+timeout, invalid output), Cursor **blocks** the matched command rather than letting it run
+unapproved. When Pushary is reachable but you don't answer in time, it falls back to Cursor's
+own in-editor approval prompt.

package/data/cursor-plugin/commands/notify-when-done.md

@@ -0,0 +1,14 @@
+---
+name: notify-when-done
+description: Send a Pushary push summarizing what changed when the current task finishes.
+---
+
+When you finish the current task, send a Pushary push notification so the user knows it's done — even if they have stepped away from the editor.
+
+Call `send_notification` with:
+- `title`: a short summary (under 60 chars) of what was completed
+- `body`: one line on the outcome (under 200 chars)
+- `agentName`: `"Cursor - {project}"`
+- `context`: `{ type: "task_complete", summary, filesChanged, nextSteps }`
+
+Send a single notification for the task. If the task fails instead, send `context.type: "error"` with `errorMessage` and the file where it failed.

package/data/cursor-plugin/commands/pushary-test.md

@@ -0,0 +1,13 @@
+---
+name: pushary-test
+description: Send a test Pushary push notification to confirm notifications are working.
+---
+
+Send a test push notification with the Pushary `send_notification` tool so the user can confirm delivery on their phone.
+
+Call `send_notification` with:
+- `title`: "Pushary test"
+- `body`: "If you can read this on your phone, Pushary is working."
+- `agentName`: `"Cursor - {project}"` (use the current project folder name)
+
+Then tell the user it was sent and to check their device. If the call fails, report the error and remind them to set the `PUSHARY_API_KEY` environment variable and sign in at https://pushary.com.

package/data/cursor-plugin/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeShellExecution": [
+      {
+        "command": "node ./scripts/pushary-gate.mjs",
+        "matcher": "\\brm\\b|\\brmdir\\b|\\bunlink\\b|\\bmkfs|\\bdd\\b|\\bshutdown\\b|\\breboot\\b|\\bpkill\\b|\\bkillall\\b|\\bsystemctl\\b|--force\\b|force-push|reset --hard|\\brebase\\b|\\bdrop\\b|\\bDROP\\b|\\btruncate\\b|\\bTRUNCATE\\b|delete from|DELETE FROM|\\bdeploy\\b|\\bpublish\\b|\\brelease\\b|\\bmigrate\\b",
+        "timeout": 60,
+        "failClosed": true
+      }
+    ]
+  }
+}

package/data/cursor-plugin/mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "pushary": {
+      "type": "http",
+      "url": "https://pushary.com/api/mcp/mcp",
+      "headers": {
+        "Authorization": "Bearer ${PUSHARY_API_KEY}"
+      }
+    }
+  }
+}

package/data/cursor-plugin/rules/pushary.mdc

@@ -0,0 +1,40 @@
+---
+description: Pushary is connected. Use it to ask the user questions, notify them, and gate risky commands through push.
+alwaysApply: true
+---
+
+# Pushary
+
+Pushary is connected as an MCP server. It reaches the user on their phone, so use it on your own without being asked. Assume the user may be away from the editor.
+
+## Ask the user through Pushary
+
+When Pushary is connected, it is your channel for reaching the user. Any time you would stop and ask the user something, ask it through the `ask_user` tool and wait for the answer, instead of only asking in the chat. This covers all of your questions:
+
+- Yes or no. Use type "confirm".
+- Multiple choice. Use type "select" with 2 to 6 options.
+- A name, a path, a value, or other free text. Use type "input".
+- Approval of a plan or an approach before you start. Use type "select" with the options the user is choosing between, or "confirm" to approve a single plan.
+
+`ask_user` blocks and returns `{ answered, value }`. Always set `context` to one line on what you are doing, and set `agentName` to "Cursor - {project}". If `answered` is false, you did not get an answer in time: pick the safe default or stop and tell the user. Never assume approval.
+
+If the user answers in the chat before the push comes back, continue and call `cancel_question` with the correlationId to clean up.
+
+## Notify the user
+
+Use `send_notification` when something is worth the user's attention:
+
+- A task of 3 or more steps finishes. Use `context.type` "task_complete" with a short summary and the files changed.
+- A build, test, or deploy fails. Use `context.type` "error" with the error message.
+- A long job finishes, such as a migration, refactor, or generation.
+
+## Risky commands are gated for you
+
+Risky shell commands (rm, force push, history rewrites, database drops, deploys, systemctl, and similar) are sent to the user for phone approval automatically by the plugin's hook, following the user's Pushary policy. You do not need to ask separately for those. For anything else destructive that the hook might not catch, ask first with `ask_user`.
+
+## Keep it tidy
+
+- Keep titles under 60 characters and bodies under 200. Put detail in the `context` object, not the title.
+- Send at most 3 notifications per task unless the user asks for more.
+
+For the full tool reference, with every parameter, examples, and return values, see the pushary skill.

package/data/cursor-plugin/scripts/pushary-gate.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+// Pushary gate — Cursor `beforeShellExecution` hook.
+//
+// Routes risky shell commands through your Pushary permission policy before they
+// run. Which commands reach this gate is the `matcher` in ../hooks/hooks.json; what
+// HAPPENS to a matched command is decided by your dashboard policy (the same policy
+// the @pushary/agent-hooks CLI uses for Claude Code), so behavior is consistent
+// across agents.
+//
+// It honors, per tool ("Bash"): auto-approve, the four approval modes
+// (push_only / push_first / notify_only / terminal_only), the timeout action
+// (approve / deny / escalate), a live mode override, and the kill switch — all
+// scoped to the Cursor conversation. Policy is cached in the temp dir for 5 minutes
+// with a stale-fallback, and requests retry.
+//
+// Self-contained: no dependencies, uses the global fetch (Node 18+).
+//
+// Contract (https://cursor.com/docs/hooks):
+//   stdin  : { "command": string, "cwd": string, "conversation_id": string, ... }
+//   stdout : { "permission": "allow" | "deny" | "ask", "user_message"?, "agent_message"? }
+//
+// Failure model: every handled path writes a decision and exits 0. Network/parse
+// errors and no-policy fall back to "ask" (Cursor's own prompt) — it never silently
+// allows a risky command. A 55s hard guard guarantees a decision before the hook's
+// `failClosed` deadline; only a catastrophic crash (e.g. Node missing) leaves no
+// output, in which case `failClosed: true` blocks the command rather than allowing
+// it unapproved.
+
+import { createHash } from 'node:crypto'
+import { hostname, tmpdir } from 'node:os'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const BASE_URL = 'https://pushary.com'
+const MCP_URL = `${BASE_URL}/api/mcp/mcp`
+const POLICY_CACHE_TTL_MS = 5 * 60 * 1000
+const MAX_BLOCK_MS = 45_000 // longest we can wait before Cursor's hook timeout
+const WAIT_CHUNK_MS = 20_000 // per wait_for_answer long-poll
+const POLL_GAP_MS = 1_500 // pause between polls after a transient error
+const NET_TIMEOUT_MS = 27_000 // abort a single MCP request
+const POLICY_TIMEOUT_MS = 10_000
+const MODE_TIMEOUT_MS = 3_000
+const HARD_GUARD_MS = 55_000 // force a graceful "ask" before failClosed (60s) fires
+
+// ── Cursor decisions ──────────────────────────────────────────────────────────
+const ALLOW = { permission: 'allow' }
+const ask = (agentMessage) => (agentMessage ? { permission: 'ask', agent_message: agentMessage } : { permission: 'ask' })
+const deny = (agentMessage) => ({ permission: 'deny', user_message: 'Command denied via Pushary.', agent_message: agentMessage })
+
+let done = false
+const respond = (decision) => {
+  if (done) return
+  done = true
+  process.stdout.write(JSON.stringify(decision))
+  process.exit(0)
+}
+
+// Backstop: if anything hangs, return "ask" rather than letting the hook time out
+// (which, with failClosed, would block the command).
+setTimeout(() => respond(ask()), HARD_GUARD_MS).unref()
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+const clamp = (n, lo, hi) => Math.min(Math.max(n, lo), hi)
+
+const withRetry = async (fn, attempts) => {
+  let lastError
+  for (let i = 0; i < attempts; i += 1) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (i < attempts - 1) await sleep(300 * (i + 1))
+    }
+  }
+  throw lastError
+}
+
+const readStdin = async () => {
+  let raw = ''
+  for await (const chunk of process.stdin) raw += chunk
+  return raw
+}
+
+const getMachineId = () => createHash('sha256').update(hostname()).digest('hex').slice(0, 8)
+
+// Env first. CLI installs inject the key into the sibling mcp.json, so fall back to
+// that. This lets the gate work even when Cursor's GUI does not pass the shell env.
+const resolveApiKey = () => {
+  const fromEnv = process.env.PUSHARY_API_KEY
+  if (fromEnv) return fromEnv
+  try {
+    const mcpPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'mcp.json')
+    const auth = JSON.parse(readFileSync(mcpPath, 'utf-8'))?.mcpServers?.pushary?.headers?.Authorization ?? ''
+    const key = auth.replace(/^Bearer\s+/i, '').trim()
+    if (/^pk_[a-z0-9]+\.[a-z0-9]+$/i.test(key)) return key
+  } catch {}
+  return undefined
+}
+
+// ── MCP transport (JSON or SSE) ─────────────────────────────────────────────────
+const parseMcpBody = (body, contentType) => {
+  if (contentType && contentType.includes('text/event-stream')) {
+    let last = null
+    for (const frame of body.split(/\r?\n\r?\n/)) {
+      const data = frame
+        .split(/\r?\n/)
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(5).trimStart())
+        .join('\n')
+        .trim()
+      if (!data) continue
+      try {
+        last = JSON.parse(data)
+      } catch {}
+    }
+    if (!last) throw new Error('empty SSE response')
+    return last
+  }
+  return JSON.parse(body)
+}
+
+const callTool = async (apiKey, name, args) => {
+  const response = await fetch(MCP_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method: 'tools/call', params: { name, arguments: args } }),
+    signal: AbortSignal.timeout(NET_TIMEOUT_MS),
+  })
+  const text = await response.text()
+  if (!response.ok) throw new Error(`Pushary MCP ${response.status}`)
+  const rpc = parseMcpBody(text, response.headers.get('content-type'))
+  if (rpc.error) throw new Error(rpc.error.message || 'Pushary MCP error')
+  const payload = rpc.result?.content?.[0]?.text
+  if (!payload) throw new Error('empty Pushary response')
+  return JSON.parse(payload)
+}
+
+const getJson = async (path, apiKey, timeoutMs) => {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (!response.ok) throw new Error(`GET ${path} ${response.status}`)
+  return response.json()
+}
+
+// ── Policy (mirrors @pushary/agent-hooks policy.ts) ──────────────────────────────
+const isPolicyConfig = (d) =>
+  !!d && typeof d === 'object' && Array.isArray(d.policies) && typeof d.defaultTimeoutSeconds === 'number' && typeof d.defaultTimeoutAction === 'string'
+
+const policyCacheFile = (apiKey) => join(tmpdir(), `pushary-policy-${createHash('sha256').update(apiKey).digest('hex').slice(0, 12)}.json`)
+
+const getPolicy = async (apiKey) => {
+  const path = policyCacheFile(apiKey)
+  let stale = null
+  if (existsSync(path)) {
+    try {
+      const cached = JSON.parse(readFileSync(path, 'utf-8'))
+      if (isPolicyConfig(cached)) {
+        if (!cached._cachedAt || Date.now() - cached._cachedAt < POLICY_CACHE_TTL_MS) return cached
+        stale = cached
+      }
+    } catch {}
+  }
+  try {
+    const fresh = await withRetry(async () => {
+      const raw = await getJson('/api/mcp/policy', apiKey, POLICY_TIMEOUT_MS)
+      if (!isPolicyConfig(raw)) throw new Error('invalid policy')
+      return raw
+    }, 2)
+    try {
+      writeFileSync(path, JSON.stringify({ ...fresh, _cachedAt: Date.now() }), 'utf-8')
+    } catch {}
+    return fresh
+  } catch (error) {
+    if (stale) return stale
+    throw error
+  }
+}
+
+const resolvePolicy = (config, toolName, modeOverride) => {
+  const base =
+    config.policies.find((p) => p.tool === toolName) ??
+    config.policies.find((p) => p.tool === '*') ??
+    {
+      tool: toolName,
+      timeoutSeconds: config.defaultTimeoutSeconds,
+      timeoutAction: config.defaultTimeoutAction,
+      mode: config.defaultMode ?? 'push_first',
+      pushFirstSeconds: config.defaultPushFirstSeconds ?? 20,
+    }
+  const effective = modeOverride ?? config.modeOverride
+  return effective ? { ...base, mode: effective } : base
+}
+
+const APPROVAL_MODES = ['push_only', 'terminal_only', 'push_first', 'notify_only']
+const fetchModeState = async (apiKey, sessionId) => {
+  try {
+    const path = sessionId ? `/api/mcp/mode?session=${encodeURIComponent(sessionId)}` : '/api/mcp/mode'
+    const data = await getJson(path, apiKey, MODE_TIMEOUT_MS)
+    const mode = data?.override?.mode
+    return { mode: APPROVAL_MODES.includes(mode) ? mode : null, kill: data?.kill === true }
+  } catch {
+    return { mode: null, kill: false }
+  }
+}
+
+// ── ask / wait ───────────────────────────────────────────────────────────────
+const askArgs = (command, project, ident) => ({
+  question: `Allow this command?\n\n${command}`,
+  type: 'confirm',
+  context: `Cursor agent wants to run this in ${project}`,
+  agentName: ident.agentName,
+  sessionId: ident.sessionId,
+  machineId: ident.machineId,
+  toolName: 'Bash',
+  wait: false,
+})
+
+const pollForAnswer = async (apiKey, correlationId, deadlineMs) => {
+  while (Date.now() < deadlineMs) {
+    const remaining = clamp(deadlineMs - Date.now(), 1_000, WAIT_CHUNK_MS)
+    try {
+      const answer = await callTool(apiKey, 'wait_for_answer', { correlationId, timeoutMs: remaining })
+      if (answer?.answered) return answer
+    } catch {
+      if (Date.now() + POLL_GAP_MS >= deadlineMs) break
+      await sleep(POLL_GAP_MS)
+      continue
+    }
+    if (Date.now() + POLL_GAP_MS >= deadlineMs) break
+    await sleep(POLL_GAP_MS)
+  }
+  return { answered: false }
+}
+
+const fromTimeoutAction = (action, deniedReason) =>
+  action === 'approve' ? ALLOW : action === 'deny' ? deny(deniedReason) : ask()
+
+const DENIED = 'The user denied this command via a Pushary push approval. Do not run it — propose an alternative or ask how to proceed.'
+
+// push_only: wait up to the policy timeout, then apply the timeout action.
+const handlePushOnly = async (apiKey, command, project, ident, timeoutSeconds, timeoutAction) => {
+  let asked
+  try {
+    asked = await withRetry(() => callTool(apiKey, 'ask_user', askArgs(command, project, ident)), 3)
+  } catch {
+    return fromTimeoutAction(timeoutAction, 'Push notification failed; denied per your Pushary policy.')
+  }
+  if (!asked?.correlationId) return ask()
+
+  const realMs = Math.max(timeoutSeconds, 1) * 1000
+  const cap = Math.min(realMs, MAX_BLOCK_MS)
+  const answer = await pollForAnswer(apiKey, asked.correlationId, Date.now() + cap)
+  if (answer.answered) return answer.value === 'yes' ? ALLOW : deny(DENIED)
+
+  // If Cursor's hook limit cut us off before the configured timeout, hand off to
+  // Cursor's own prompt rather than misapplying the policy's timeout action.
+  if (cap >= realMs) return fromTimeoutAction(timeoutAction, 'No response within the approval timeout; denied per your Pushary policy.')
+  return ask()
+}
+
+// push_first: race the push for a short window, then fall back to Cursor's prompt.
+const handlePushFirst = async (apiKey, command, project, ident, pushFirstSeconds) => {
+  let asked
+  try {
+    asked = await withRetry(() => callTool(apiKey, 'ask_user', askArgs(command, project, ident)), 3)
+  } catch {
+    return ask()
+  }
+  if (!asked?.correlationId) return ask()
+
+  const cap = Math.min(Math.max(pushFirstSeconds, 1) * 1000, MAX_BLOCK_MS)
+  const answer = await pollForAnswer(apiKey, asked.correlationId, Date.now() + cap)
+  if (answer.answered) return answer.value === 'yes' ? ALLOW : deny(DENIED)
+  return ask('Sent to your phone via Pushary — you can also approve here.')
+}
+
+// notify_only: fire an awareness notification, let Cursor's prompt decide.
+const handleNotifyOnly = async (apiKey, command, project, ident) => {
+  try {
+    await callTool(apiKey, 'send_notification', {
+      title: 'Agent needs approval',
+      body: command.slice(0, 180),
+      agentName: ident.agentName,
+      sessionId: ident.sessionId,
+      machineId: ident.machineId,
+    })
+  } catch {}
+  return ask()
+}
+
+const main = async () => {
+  let input
+  try {
+    const raw = await readStdin()
+    input = raw.trim() ? JSON.parse(raw) : {}
+  } catch {
+    return respond(ask())
+  }
+
+  const command = typeof input.command === 'string' ? input.command.trim() : ''
+  if (!command) return respond(ask())
+
+  const apiKey = resolveApiKey()
+  if (!apiKey) {
+    return respond(
+      ask('Pushary is not configured: set the PUSHARY_API_KEY environment variable (get a key at https://pushary.com) to route this approval to your phone.')
+    )
+  }
+
+  const project = basename(input.cwd || process.cwd()) || 'workspace'
+  const sessionId = typeof input.conversation_id === 'string' ? input.conversation_id : undefined
+  const ident = { agentName: `Cursor - ${project}`, sessionId, machineId: getMachineId() }
+
+  try {
+    const [policy, modeState] = await Promise.all([getPolicy(apiKey), fetchModeState(apiKey, sessionId)])
+
+    if (modeState.kill) return respond(deny('Stopped by user — this agent was halted from Pushary. Do not run this command.'))
+
+    const tool = resolvePolicy(policy, 'Bash', modeState.mode)
+    if (tool.timeoutSeconds === 0 && tool.timeoutAction === 'approve') return respond(ALLOW)
+
+    switch (tool.mode) {
+      case 'terminal_only':
+        return respond(ask())
+      case 'notify_only':
+        return respond(await handleNotifyOnly(apiKey, command, project, ident))
+      case 'push_only':
+        return respond(await handlePushOnly(apiKey, command, project, ident, tool.timeoutSeconds, tool.timeoutAction))
+      case 'push_first':
+      default:
+        return respond(await handlePushFirst(apiKey, command, project, ident, tool.pushFirstSeconds))
+    }
+  } catch (error) {
+    process.stderr.write(`[pushary-gate] ${error?.message ?? error}\n`)
+    return respond(ask())
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`[pushary-gate] fatal: ${error?.message ?? error}\n`)
+  respond(ask())
+})