@pushary/agent-hooks 0.65.0 → 0.67.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.67.0
+
+### The VS Code agent can now ask for approval on your phone
+
+Setup has a VS Code option. It installs a Pushary agent plugin, connects the MCP
+tools so the agent can notify you and ask you questions, and registers a
+permission gate so a risky terminal command reaches your phone before it runs.
+The policy behind it is the one your other agents already use, so a rule you
+wrote for Claude Code applies here too.
+
+Two things about VS Code shaped how this works.
+
+VS Code reads a hook's matcher but does not act on it, so the gate is called for
+every tool the agent uses, including reading a file. It therefore decides for
+itself, and for anything that is not a risky shell command it returns straight
+away without touching the disk or the network.
+
+And a plugin folder does nothing until VS Code is told where it is. Setup adds
+that entry to your settings.json. That file usually has comments in it, and
+rewriting it as plain JSON would delete every one of them, so an existing file
+is edited one line at a time and left otherwise byte for byte identical. If your
+settings already have a plugin list with comments around it, setup does not
+guess: it prints the single line to paste and names the file.
+
+Unlike Cursor, VS Code hooks cannot ask the editor to block a command on the
+plugin's behalf. So when Pushary cannot reach you, or cannot reach its own
+server, the gate hands the decision to VS Code's own approval prompt rather than
+letting the command through.
+
+`pushary clean` removes all of it again, the settings.json entry included, and
+`pushary doctor` checks the three things that can be silently wrong: whether the
+plugin is registered at all, whether the gate script resolves, and whether your
+key is linked.
+
+## 0.66.0
+
+### Setup waited three minutes for a step that takes longer than three minutes
+
+If you already had the app installed and signed in, pairing resolved in seconds
+and this never came up. If you did not, it could not work at all.
+
+Scanning the QR without the app opens a page that sends you to the store. Install
+it, sign in, subscribe, come back, scan: that is never three minutes. The CLI had
+given up and cancelled the pairing long before, so a first-time user's first scan
+was guaranteed to fail, and the only route through was to notice the terminal had
+stopped waiting and run setup again.
+
+Setup now waits as long as the code is actually valid, and after the first
+45 seconds the spinner says what to do if the app is not installed yet. Ctrl-C
+still exits cleanly and cancels the pairing, so nothing holds you there.
+
+The window itself is unchanged in what protects it: a pairing id is 128 bits,
+single use, deleted the moment it is claimed, and authorising one requires a
+signed-in session for the owning account and the public key you physically
+scanned.
+
 ## 0.65.0
 
 ### The pairing QR now works when you scan it with your phone camera

package/data/vscode-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "name": "pushary",
+  "description": "Push notifications, human-in-the-loop questions, and permission gating for your AI 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",
+    "url": "https://pushary.com"
+  },
+  "homepage": "https://pushary.com",
+  "repository": "https://github.com/Pushary/vscode-plugin",
+  "license": "MIT",
+  "keywords": [
+    "notifications",
+    "push",
+    "human-in-the-loop",
+    "permissions",
+    "approvals",
+    "mcp",
+    "agent",
+    "control-panel",
+    "ask",
+    "alerts"
+  ],
+  "skills": "skills/",
+  "hooks": "hooks/hooks.json",
+  "mcpServers": ".mcp.json"
+}

package/data/vscode-plugin/.mcp.json

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

package/data/vscode-plugin/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `PreToolUse` permission gate for the VS Code agent, routing risky terminal commands to phone approval through your Pushary policy.
+- Self-filtering gate script, because VS Code parses but does not enforce a hook `matcher`. Non-matching tool calls return without touching disk or network.
+- MCP server wiring for `send_notification`, `ask_user`, `wait_for_answer`, and `cancel_question`.
+- Pushary skill and the `/pushary-test` and `/notify-when-done` commands.
+- API key resolution from `PUSHARY_API_KEY`, the plugin `.mcp.json`, or `~/.pushary/config.json`, so the plugin works when VS Code is launched from the Dock without a shell profile.

package/data/vscode-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/vscode-plugin/README.md

@@ -0,0 +1,136 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Pushary" width="72" height="72" />
+</p>
+
+<h1 align="center">Pushary for VS Code</h1>
+
+<p align="center">A control panel for your AI 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 the VS Code agent 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 chat panel.
+
+3. Gate. Risky terminal 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 VS Code's own approval prompt, so nothing dangerous runs silently.
+
+## Requirements
+
+- VS Code with agent plugins enabled (`chat.plugins.enabled`). This setting can be managed by your organization.
+- Node.js 20 or newer on your PATH. The gate runs as a `node` subprocess.
+- A Pushary API key from https://pushary.com.
+
+## Install
+
+### Option 1: CLI (recommended)
+
+This installs the plugin, registers it with VS Code, and links your API key. It also sets up Claude Code, Codex, Cursor, and Hermes if you use them.
+
+```bash
+npx @pushary/agent-hooks@latest setup
+```
+
+To configure only VS Code:
+
+```bash
+npx @pushary/agent-hooks@latest setup --agents vscode
+```
+
+### Option 2: Install from source
+
+Run **Chat: Install Plugin From Source** from the Command Palette and enter:
+
+```
+https://github.com/Pushary/vscode-plugin
+```
+
+Then set your API key (see below).
+
+### Option 3: Point VS Code at a local folder
+
+Clone this repository, then add the absolute path to your VS Code `settings.json`:
+
+```json
+{
+  "chat.pluginLocations": {
+    "/absolute/path/to/vscode-plugin": true
+  }
+}
+```
+
+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, falling back to the key `pushary setup` writes to `~/.pushary/config.json`.
+
+```bash
+echo 'export PUSHARY_API_KEY="pk_xxx.sk_xxx"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+macOS and Windows do not pass your shell profile to apps launched from the Dock, Finder, or the Start menu, so an `export` in `.zshrc` is often invisible to VS Code. The `~/.pushary/config.json` fallback exists for exactly this case, which is why the CLI install is the recommended path.
+
+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 VS Code to the Pushary tools: `send_notification`, `ask_user`, `wait_for_answer`, `cancel_question` |
+| Skill | `skills/pushary/SKILL.md` | Full tool reference: parameters, examples, return values, and the proactive-use guidance |
+| 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. `RISKY_COMMAND` in `scripts/pushary-gate.mjs` decides which commands get checked at all. Everything else passes straight through with no disk or network access.
+
+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 behavior stays the same across agents.
+
+### Why the filtering lives in the script
+
+VS Code parses a hook's `matcher` but does not enforce it, so `PreToolUse` fires on every tool call the agent makes, including reads and searches. `hooks/hooks.json` therefore declares no matcher: one there would do nothing, and would only read as a promise the file cannot keep.
+
+The one and only gate is `RISKY_COMMAND` in `scripts/pushary-gate.mjs`. To change which commands need approval, edit that regex. Everything else returns immediately without touching the disk or the network.
+
+## Failure behavior
+
+Every path returns a decision. Network errors, a missing API key, and unparseable input all fall back to `ask`, which hands the decision to VS Code's own approval prompt rather than allowing the command unapproved. A 55 second guard guarantees output before the hook's 60 second timeout.
+
+## Cross-tool compatibility
+
+This repository uses the `.claude-plugin/plugin.json` layout, which VS Code, GitHub Copilot CLI, and Claude Code all detect. That is also what makes `${CLAUDE_PLUGIN_ROOT}` available in `hooks/hooks.json`, which the Copilot-format layout does not define.
+
+The layout is portable; this plugin is not meant to be. `hooks/hooks.json` uses VS Code's flat hook form, and the gate speaks VS Code's tool names, so treat this as a VS Code plugin that happens to sit in a portable folder shape.
+
+Claude Code users are served by `npx @pushary/agent-hooks setup --agents claude_code`, which installs a hook built for Claude Code's own tool names and matcher format. Do not install this directory as a Claude Code plugin as well: at best it duplicates the MCP server, and the two installs would fight over the same approvals.
+
+## Development
+
+`skills/pushary/SKILL.md` mirrors the Pushary skill that ships with `@pushary/agent-hooks`. Keep the two the same.
+
+Test the gate without VS Code:
+
+```bash
+echo '{"hook_event_name":"PreToolUse","tool_name":"runTerminalCommand","tool_input":{"command":"rm -rf build"},"cwd":"/tmp"}' \
+  | node scripts/pushary-gate.mjs
+```
+
+## Security
+
+This repository has no secrets. Your key is read at runtime from `PUSHARY_API_KEY`, the plugin `.mcp.json`, or `~/.pushary/config.json`. The gate script has no dependencies and only talks to pushary.com. Command text is redacted for common secret shapes before it is sent. Read `scripts/pushary-gate.mjs` to see exactly what it sends. See `SECURITY.md` for details.
+
+## License
+
+MIT. See `LICENSE`.

package/data/vscode-plugin/SECURITY.md

@@ -0,0 +1,56 @@
+# 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 VS Code to the Pushary MCP server at `https://pushary.com/api/mcp/mcp` using
+your API key. The key is read at runtime from the `PUSHARY_API_KEY` environment variable, the
+plugin's `.mcp.json` (written by the CLI installer), or `~/.pushary/config.json`. No key is
+committed to this repository.
+
+The permission gate (`scripts/pushary-gate.mjs`) sends nothing for the overwhelming majority of
+tool calls. It only contacts Pushary when the tool is a terminal tool **and** the command matches
+`RISKY_COMMAND` in the script. For such a command it sends, over HTTPS to Pushary:
+
+- the command text, with common secret shapes (API keys, bearer tokens, `password=`, long base64
+  runs) redacted first,
+- the basename of the working directory (for example `my-repo`, not the full path),
+- an agent label (`VS Code - <project>`),
+- the VS Code chat session id, so the dashboard kill switch and per-session mode can target this
+  session,
+- a machine id, which is the first 8 hex characters of a SHA-256 of your hostname and 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. The gate 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, so read it before installing.
+
+## Failure behavior
+
+Unlike the Cursor plugin, VS Code hooks have no `failClosed` option, so the gate cannot ask VS
+Code to block a command on its behalf. It is built so that every handled failure degrades to
+`permissionDecision: "ask"`, which forces VS Code's own approval prompt instead of allowing the
+command:
+
+- no API key, unreachable network, invalid policy, or an unparseable response: `ask`
+- no answer from your phone within the window: `ask`, unless your policy's timeout action is
+  explicitly `deny`
+- kill switch active in your dashboard: `deny`
+- anything that hangs: a 55 second guard emits `ask` before the 60 second hook timeout
+
+The one case the gate cannot cover is a catastrophic crash before it produces any output, for
+example Node.js missing from PATH. VS Code treats a non-zero exit with no decision as a
+non-blocking warning and continues, at which point your normal VS Code terminal approval settings
+apply. If you have auto-approve enabled for terminal commands in VS Code, that command would run
+without a Pushary approval. Keep VS Code's own terminal approval on if that matters to you.
+
+## Hook execution model
+
+Hooks execute shell commands with the same permissions as VS Code. This one runs
+`node scripts/pushary-gate.mjs` on every agent tool call. Review the script before installing, and
+treat any plugin that registers hooks the same way.

package/data/vscode-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`: `"VS Code - {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/vscode-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`: `"VS Code - {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/vscode-plugin/hooks/hooks.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pushary-gate.mjs\"",
+        "timeout": 60
+      }
+    ]
+  }
+}