@pushary/agent-hooks 0.11.1 → 0.12.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())
+})

package/data/cursor-plugin/skills/pushary/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: pushary
+description: Push notifications and human-in-the-loop for AI coding agents. Send alerts when tasks finish, ask questions (yes/no, multiple choice, or free text) via push, and get answers from the user's lock screen. Use these tools proactively — do not wait for the user to ask for notifications. Works with Cursor, Claude Code, Windsurf, Hermes, and any MCP client.
+---
+
+# Pushary — Push Notifications for AI Agents
+
+Pushary is an MCP server that gives you three capabilities:
+
+1. **Send push notifications** to the user's phone or desktop when a task finishes or an error occurs.
+2. **Ask questions** via push — yes/no, multiple choice, or free text — and wait for the user's answer.
+3. **Send rich context notifications** with file changes, error details, next steps, and embedded questions.
+
+Use these tools proactively. Do not wait for the user to ask for notifications.
+
+## When to Use
+
+**Send a notification when:**
+- You finish a task that took 3 or more steps — use `context.type = "task_complete"`
+- A build, test suite, or deployment fails — use `context.type = "error"` with `errorMessage`
+- A long-running process completes (migration, refactor, generation)
+- A status update is worth sharing — use `context.type = "info"`
+
+**Ask with type "confirm" when:**
+- You need confirmation before a destructive or irreversible action
+- Binary decision: proceed or abort
+
+**Ask with type "select" when:**
+- Multiple implementation approaches exist (2-6 options)
+- The user needs to pick from a known set
+
+**Ask with type "input" when:**
+- You need a name, path, value, or free-text decision
+- The options cannot be enumerated in advance
+
+**Do NOT notify when:**
+- The task is trivial or single-step
+- The question can be answered from context without user input
+- You already sent 3 notifications for the current task (unless the user explicitly asked for more)
+
+## Setup
+
+Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+
+```bash
+npx @pushary/agent-hooks@latest setup
+```
+
+Or add Pushary manually to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "pushary": {
+      "type": "http",
+      "url": "https://pushary.com/api/mcp/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+
+After setup, verify with:
+
+```bash
+npx @pushary/agent-hooks@latest doctor
+```
+
+## Tools
+
+### send_notification
+
+Send a one-way push notification to the user. Optionally include structured context for a rich detail page.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| title | string | Yes | Notification title (max 100 chars, aim for under 60) |
+| body | string | Yes | Notification body (max 500 chars, aim for under 200) |
+| url | string | No | URL opened when tapped. Ignored if context is provided. |
+| agentName | string | No | Identifies which agent sent this (e.g., "Claude Code - myproject") |
+| iconUrl | string | No | Custom notification icon URL |
+| imageUrl | string | No | Large image shown in the notification |
+| subscriberIds | string[] | No | Target specific subscriber IDs |
+| externalIds | string[] | No | Target by external IDs |
+| tags | string[] | No | Target by subscriber tags |
+| context | object | No | Structured context for a rich detail page (see below) |
+
+**Context object:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| type | "task_complete" / "error" / "info" | The kind of notification |
+| summary | string | Short summary of what happened |
+| details | string[] | Bullet-point details |
+| filesChanged | string[] | List of files that were changed |
+| errorMessage | string | Error message (for error type) |
+| errorFile | string | File path where the error occurred |
+| nextSteps | string | Suggested next steps for the user |
+| askQuestion | object | Embed a decision prompt in the notification (see below) |
+
+**Embedded askQuestion:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| question | string | A follow-up question shown below the context |
+| type | "confirm" / "select" / "input" | Question type (default: confirm) |
+| options | string[] | Options for select type (2-6 items) |
+
+When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
+
+**Example — task completed with context:**
+
+```json
+{
+  "title": "Refactoring complete",
+  "body": "Extracted 3 shared components across 12 files",
+  "agentName": "Claude Code - pushary repo",
+  "context": {
+    "type": "task_complete",
+    "summary": "Extracted shared Button, Modal, and Card components from 12 files",
+    "filesChanged": ["src/components/Button.tsx", "src/components/Modal.tsx", "src/components/Card.tsx"],
+    "nextSteps": "Run the test suite to verify no regressions"
+  }
+}
+```
+
+**Example — error with embedded question:**
+
+```json
+{
+  "title": "Build failed",
+  "body": "TypeScript error in auth.ts:42",
+  "agentName": "Claude Code - api-server",
+  "context": {
+    "type": "error",
+    "errorMessage": "Type 'string' is not assignable to type 'AuthToken'",
+    "errorFile": "src/auth.ts:42",
+    "summary": "The auth token type changed upstream and this file needs updating",
+    "askQuestion": {
+      "question": "Should I update the type or revert the upstream change?",
+      "type": "select",
+      "options": ["Update the type in auth.ts", "Revert the upstream change", "Skip for now"]
+    }
+  }
+}
+```
+
+### ask_user
+
+Send a question to the user via push notification and wait for their answer. By default, this tool **blocks** until the user responds or the timeout is reached — no need to call `wait_for_answer` separately.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| question | string | Yes | The question to ask (max 500 chars) |
+| type | "confirm" / "select" / "input" | No | Question type (default: confirm) |
+| options | string[] | No | Choices for select type (2-6 options). Required when type is select. |
+| placeholder | string | No | Placeholder text for input type (max 200 chars) |
+| context | string | No | What the agent is working on, shown above the question (max 500 chars) |
+| wait | boolean | No | Wait for the answer before returning (default: true). Set false for manual polling. |
+| timeoutMs | integer | No | Max wait time in ms (max 55000). Uses site policy if omitted. |
+| agentName | string | No | Identifies which agent is asking. Format: "{Agent} - {project}" (e.g., "Claude Code - myproject") |
+| callbackUrl | string | No | Webhook URL to POST the answer to when the user responds |
+| subscriberIds | string[] | No | Target specific subscriber IDs |
+| externalIds | string[] | No | Target by external IDs |
+| tags | string[] | No | Target by subscriber tags |
+
+**Returns (when wait=true, default):**
+- `{ "answered": true, "value": "yes", "correlationId": "uuid" }` — user responded
+- `{ "answered": false, "timedOut": true, "correlationId": "uuid" }` — timeout reached
+
+**Returns (when wait=false):**
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` — use `wait_for_answer` to poll
+
+**Example — confirm (yes/no):**
+
+```json
+{
+  "question": "Delete the 3 unused migration files?",
+  "type": "confirm",
+  "context": "Cleaning up old database migrations in db/migrate/",
+  "agentName": "Claude Code - myproject"
+}
+```
+
+**Example — select (multiple choice):**
+
+```json
+{
+  "question": "Which auth strategy should I use?",
+  "type": "select",
+  "options": ["JWT tokens", "Session cookies", "OAuth2 + PKCE"],
+  "context": "Setting up authentication for the new API endpoints",
+  "agentName": "Claude Code - api-server"
+}
+```
+
+**Example — input (free text):**
+
+```json
+{
+  "question": "What should the new API endpoint path be?",
+  "type": "input",
+  "placeholder": "/api/v2/...",
+  "context": "Creating a new REST endpoint for user preferences",
+  "agentName": "Cursor - frontend"
+}
+```
+
+### wait_for_answer
+
+Poll for the user's response to a question sent via `ask_user` with `wait: false`. Not needed when using the default blocking mode.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| correlationId | string (uuid) | Yes | The correlationId from ask_user |
+| timeoutMs | integer | No | How long to wait (default 30000, max 55000) |
+
+**Returns:**
+- `{ "answered": true, "value": "yes" }` — user responded
+- `{ "answered": false }` — timeout reached, no answer yet
+
+### cancel_question
+
+Cancel a pending question so it can no longer be answered. Use when the question becomes irrelevant (e.g., you found the answer another way or the user responded in chat).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
+
+## Permission Gating (REQUIRED)
+
+Before executing any of the following, you MUST call `ask_user` with type "confirm" and wait for approval. Do NOT proceed without an explicit "yes" from the user:
+
+- File deletion (`rm`, `unlink`, any destructive file operation)
+- Database mutations (`DROP`, `DELETE`, `TRUNCATE`, migrations)
+- Deployment commands (`deploy`, `push`, `publish`, `release`)
+- System administration (`systemctl`, `service`, package install/remove)
+- Git operations that rewrite history (`reset --hard`, `push --force`, `rebase`)
+- Network configuration changes (firewall, DNS, proxy)
+- Any command the user has flagged as dangerous
+
+If `ask_user` returns `answered: false`, do NOT execute the command. Send a notification that the operation was skipped due to no response.
+
+This is not optional. Treat it as a hard constraint, not a suggestion.
+
+## Human-in-the-Loop Flow
+
+One tool call — `ask_user` blocks and returns the answer:
+
+```
+result = ask_user({
+  question: "Which auth strategy should I use?",
+  type: "select",
+  options: ["JWT tokens", "Session cookies", "OAuth2 + PKCE"],
+  context: "Setting up authentication for the new API",
+  agentName: "Claude Code - myproject"
+})
+
+if result.answered:
+    // result.value = "JWT tokens" — proceed with the chosen approach
+else:
+    // user did not respond — pick the safe default or notify and skip
+```
+
+If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
+
+## Identifying Your Agent
+
+Always pass `agentName` when you are one of multiple possible agents the user may be running. The user sees this in the notification title to know which agent is asking.
+
+**Format:** `{Agent Type} - {project or context}`
+
+**Examples:**
+- `"Claude Code - pushary repo"`
+- `"Hermes - daily-briefing"`
+- `"Cursor - frontend refactor"`
+
+## Notification Etiquette
+
+- **Titles under 60 characters.** They get truncated on phone lock screens.
+- **Bodies under 200 characters.** Concise summaries, not full explanations.
+- **Max 3 notifications per task** unless the user explicitly requests more.
+- **Use context for detail.** Put file lists, error traces, and next steps in the context object — not the notification body.
+- **Write questions as if talking to a busy person.** The user is on their phone, possibly away from their computer. Be specific: "Delete the 3 unused migration files?" is better than "Should I clean up?"
+- **Pick the right question type.** Use confirm for binary decisions, select when options are known, input when they are not.

package/dist/bin/pushary-clean.js

@@ -24,6 +24,7 @@ var CLAUDE_SETTINGS_LOCAL = join(homedir(), ".claude", "settings.local.json");
 var CLAUDE_JSON = join(homedir(), ".claude.json");
 var SKILL_DIR = join(homedir(), ".claude", "skills", "pushary");
 var CURSOR_MCP = join(".cursor", "mcp.json");
+var CURSOR_PLUGIN_DIR = join(homedir(), ".cursor", "plugins", "local", "pushary");
 var SHELL_FILES = [".zshrc", ".zprofile", ".bashrc", ".bash_profile"].map((f) => join(homedir(), f));
 var readJson = (path) => {
   try {
@@ -86,6 +87,12 @@ var main = async () => {
   } else {
     console.log(`  ${skip} Cursor MCP config ${dim("(not found)")}`);
   }
+  if (existsSync(CURSOR_PLUGIN_DIR)) {
+    rmSync(CURSOR_PLUGIN_DIR, { recursive: true });
+    console.log(`  ${check} Cursor plugin ${dim("(removed from ~/.cursor/plugins/local)")}`);
+  } else {
+    console.log(`  ${skip} Cursor plugin ${dim("(not installed)")}`);
+  }
   if (existsSync(SKILL_DIR)) {
     rmSync(SKILL_DIR, { recursive: true });
     console.log(`  ${check} Skill directory ${dim("(removed)")}`);

package/dist/bin/pushary-setup.js

@@ -13,8 +13,8 @@ import {
 } from "../chunk-IBWCHA5M.js";
 
 // bin/pushary-setup.ts
-import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync } from "fs";
-import { join, dirname } from "path";
+import { existsSync, readFileSync, writeFileSync, appendFileSync, mkdirSync, cpSync, rmSync } from "fs";
+import { join, dirname, basename } from "path";
 import { homedir } from "os";
 import { execSync } from "child_process";
 import { checkbox, input, confirm } from "@inquirer/prompts";
@@ -176,8 +176,7 @@ var printConnectInstructions = async (apiKey) => {
 // bin/pushary-setup.ts
 var CLAUDE_SETTINGS = join(homedir(), ".claude", "settings.json");
 var CLAUDE_JSON = join(homedir(), ".claude.json");
-var CURSOR_MCP = join(".cursor", "mcp.json");
-var CURSOR_RULES_DIR = join(".cursor", "rules");
+var CURSOR_PLUGIN_DIR = join(homedir(), ".cursor", "plugins", "local", "pushary");
 var CLAUDE_SKILL_DIR = join(homedir(), ".claude", "skills", "pushary");
 var CODEX_SKILL_DIR = join(homedir(), ".codex", "skills", "pushary");
 var SHELL_FILES = [".zshrc", ".zprofile", ".bashrc", ".bash_profile"].map((f) => join(homedir(), f));
@@ -297,19 +296,6 @@ var installSkillToDir = async (dir, label) => {
     writeFileSync(join(dir, "SKILL.md"), content, "utf-8");
   });
 };
-var installCursorRule = async () => {
-  await spinner("Installing Pushary rules", async () => {
-    const content = await fetchSkillContent();
-    const body = content.replace(/^---[\s\S]*?---\n*/m, "");
-    const mdc = `---
-alwaysApply: true
----
-
-${body}`;
-    if (!existsSync(CURSOR_RULES_DIR)) mkdirSync(CURSOR_RULES_DIR, { recursive: true });
-    writeFileSync(join(CURSOR_RULES_DIR, "pushary.mdc"), mdc, "utf-8");
-  });
-};
 var setupClaudeCode = async (apiKey) => {
   console.log(`
   ${bold2("Setting up Claude Code")}
@@ -469,22 +455,45 @@ var setupCodex = async (_apiKey) => {
   console.log(`  ${dim2("\u2022")} Auto-allowed tools: no permission prompts for Pushary MCP calls`);
   console.log(`  ${dim2("\u2022")} Notify handler: captures turn completions and approval requests`);
 };
+var resolveBundledPlugin = () => {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(dir, "..", "..", "data", "cursor-plugin"),
+    join(dir, "..", "data", "cursor-plugin"),
+    join(dir, "..", "..", "..", "cursor-plugin"),
+    join(dir, "..", "..", "cursor-plugin")
+  ];
+  return candidates.find((p) => existsSync(join(p, ".cursor-plugin", "plugin.json"))) ?? null;
+};
 var setupCursor = async (apiKey) => {
   console.log(`
   ${bold2("Setting up Cursor")}
 `);
-  await spinner("Adding MCP server to .cursor/mcp.json", async () => {
-    const config = readJson(CURSOR_MCP);
-    const mcpServers = config.mcpServers ?? {};
-    mcpServers.pushary = {
-      type: "http",
-      url: "https://pushary.com/api/mcp/mcp",
-      headers: { Authorization: `Bearer ${apiKey}` }
-    };
-    config.mcpServers = mcpServers;
-    writeJson(CURSOR_MCP, config);
+  const source = resolveBundledPlugin();
+  if (!source) throw new Error("bundled Cursor plugin not found in this package");
+  await spinner("Installing Pushary plugin", async () => {
+    rmSync(CURSOR_PLUGIN_DIR, { recursive: true, force: true });
+    cpSync(source, CURSOR_PLUGIN_DIR, {
+      recursive: true,
+      filter: (p) => !["tools", "node_modules", ".git", ".DS_Store"].includes(basename(p))
+    });
+  });
+  await spinner("Linking your API key", async () => {
+    const mcpPath = join(CURSOR_PLUGIN_DIR, "mcp.json");
+    const mcp = readJson(mcpPath);
+    const servers = mcp.mcpServers ?? {};
+    if (servers.pushary) {
+      servers.pushary.headers = { ...servers.pushary.headers, Authorization: `Bearer ${apiKey}` };
+      mcp.mcpServers = servers;
+      writeJson(mcpPath, mcp);
+    }
   });
-  await installCursorRule();
+  console.log();
+  console.log(`  ${dim2("What this configured:")}`);
+  console.log(`  ${dim2("\u2022")} Plugin installed to ~/.cursor/plugins/local/pushary`);
+  console.log(`  ${dim2("\u2022")} MCP tools, the always-on rule, the skill, and the permission gate`);
+  console.log(`  ${dim2("\u2022")} Risky shell commands route to push approval before they run`);
+  console.log(`  ${dim2("\u2022")} Restart Cursor (or run Developer: Reload Window) to load it`);
 };
 var saveApiKey = async (apiKey) => {
   await spinner("Saving API key to shell profile", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/agent-hooks",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Permission hooks for AI coding agents: route tool approvals through Pushary push notifications",
   "author": "Pushary <business@pushary.com>",
   "homepage": "https://pushary.com",
@@ -30,7 +30,7 @@
     "data"
   ],
   "scripts": {
-    "build": "tsup",
+    "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/mcp-http.test.ts && bun test src/retry.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/hook.test.ts"
   },