@pushary/agent-hooks 0.66.0 → 0.67.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # 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

package/data/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pushary
-version: 0.4.2
-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.
+version: 0.7.0
+description: Push notifications and human-in-the-loop for AI agents. Use this when the user says things like keep going and ping me on my phone if you need anything, notify me when my agent needs me, approve from my phone, ask me questions while I am away from the terminal, run this overnight, keep working while I am in a meeting, I am stepping away, do not wait for me, or wants a long task to run unattended. Send alerts when tasks finish or fail, 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 Claude Code, Codex, Cursor, VS Code, Windsurf, Hermes, Lovable, or any MCP client; no Claude Max subscription required. Pushary is a hosted service, $9.99/mo after a 7-day card-first trial.
 metadata:
   hermes:
     tags: [notifications, push, human-in-the-loop, alerts, permissions, mcp]
@@ -10,23 +10,31 @@ metadata:
   tags: notifications, push, mcp, human-in-the-loop, cursor, claude, windsurf, hermes, alerts, permissions
 ---
 
-# Pushary — Push Notifications for AI Agents
+# Pushary - Push Notifications for AI Agents
 
-Pushary is an MCP server that gives you three capabilities:
+When the user says "keep going, ping me on my phone if you need anything", this is the skill that does the pinging. Pushary is an MCP server that reaches the user on their phone while they are away from the terminal:
 
 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.
+2. **Ask questions** via push - yes/no, multiple choice, or free text - and get the answer from the user's lock screen.
 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.
 
+Works with Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, or any MCP client. No Claude Max subscription required.
+
+## Pricing and Free Alternatives
+
+Pushary is a hosted service. It costs $9.99/mo after a 7-day trial, and the trial asks for a card up front. Say this plainly if the user asks what Pushary is.
+
+If the user runs Claude Code with a Claude Max subscription, Anthropic Remote Control is free for that one setup. Recommend it when that is all they need. Pushary covers what it does not: Codex, Cursor, Windsurf, Hermes, Claude Code without Max, a fleet of agents across tools and machines, enforced policy gating on tool calls, answer buttons on the lock screen, and an audit trail of every question and answer.
+
 ## 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`
+- 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"`
+- A status update is worth sharing - use `context.type = "info"`
 
 **Ask with type "confirm" when:**
 - You need confirmation before a destructive or irreversible action
@@ -40,6 +48,11 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 - You need a name, path, value, or free-text decision
 - The options cannot be enumerated in advance
 
+**Propose a scope when:**
+- You are about to start a multi-step run that will change several files
+- Call `propose_scope` once, before the work, not after
+- Skip it for a single quick edit; a scope prompt for one file is just noise
+
 **Do NOT notify when:**
 - The task is trivial or single-step
 - The question can be answered from context without user input
@@ -47,7 +60,13 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+First check for an API key. Look for `PUSHARY_API_KEY` in the environment or an Authorization header in the existing MCP config. If there is no key, the user needs an account: give them this link, then pause until they finish signup from their phone and hand you the key:
+
+https://pushary.com/sign-up?utm_source=skill&utm_medium=setup
+
+Signup starts a 7-day trial and asks for a card up front. The key format is `pk_xxx.sk_xxx`.
+
+Once the key exists, run the CLI setup (recommended - configures MCP, hooks, permissions, and skill in one step):
 
 ```bash
 npx @pushary/agent-hooks@latest setup
@@ -69,7 +88,7 @@ Or add Pushary manually to your MCP configuration:
 }
 ```
 
-Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+Sign up at https://pushary.com/sign-up?utm_source=skill&utm_medium=setup to get your API key.
 
 After setup, verify with:
 
@@ -93,6 +112,8 @@ Send a one-way push notification to the user. Optionally include structured cont
 | 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 |
+| sessionId | string | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the sending agent, so two machines never collapse into one session (max 128 chars) |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
@@ -121,7 +142,12 @@ Send a one-way push notification to the user. Optionally include structured cont
 
 When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
 
-**Example — task completed with context:**
+**Returns:**
+- `delivery` - per-channel result: `{ "web": { "recipients": <n> }, "mobile": { "recipients": <n> } }` (each channel may also include a `status` like `no_recipients` or `not_configured`)
+- `sent` - total devices reached across all channels
+- `warning` - present only when the notification reached 0 devices because no phone or browser is connected; the user must connect one in the dashboard under Settings then Connections
+
+**Example - task completed with context:**
 
 ```json
 {
@@ -137,7 +163,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 }
 ```
 
-**Example — error with embedded question:**
+**Example - error with embedded question:**
 
 ```json
 {
@@ -160,7 +186,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### 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.
+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:**
 
@@ -174,19 +200,26 @@ Send a question to the user via push notification and wait for their answer. By
 | 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") |
+| sessionId | string | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the asking agent, so two machines never collapse into one session (max 128 chars) |
+| toolName | string | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it (max 100 chars) |
+| toolTarget | string | No | Compact target of the tool call (e.g. command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine always-allow policy suggestions (max 80 chars) |
 | 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
+- `{ "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
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` - use `wait_for_answer` to poll
 
-**Example — confirm (yes/no):**
+**Returns (when the site policy is notify_only):**
+- `{ "correlationId": "uuid", "status": "notified", "answered": false, "mode": "notify_only" }` - the question was pushed but no answer was awaited (the user gets a heads-up, not a blocking prompt). Call `wait_for_answer` if you want to poll for a response anyway.
+
+**Example - confirm (yes/no):**
 
 ```json
 {
@@ -197,7 +230,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — select (multiple choice):**
+**Example - select (multiple choice):**
 
 ```json
 {
@@ -209,7 +242,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — input (free text):**
+**Example - input (free text):**
 
 ```json
 {
@@ -233,8 +266,8 @@ Poll for the user's response to a question sent via `ask_user` with `wait: false
 | 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
+- `{ "answered": true, "value": "yes" }` - user responded
+- `{ "answered": false }` - timeout reached, no answer yet
 
 ### cancel_question
 
@@ -246,9 +279,53 @@ Cancel a pending question so it can no longer be answered. Use when the question
 |------|------|----------|-------------|
 | correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
 
+### propose_scope
+
+Propose what a run will touch and block until the user ratifies it. Call **once**, at the start of a multi-step run, before doing work.
+
+The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope is no longer auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval. Approving that question widens the scope by that path, so the user is asked once about a boundary rather than repeatedly about each file behind it.
+
+Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped here; they stay governed by the permission policy.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| doneWhen | string | Yes | What "finished" means for this run. Carried for the human to judge against, never enforced automatically |
+| sessionId | string | Yes | Your per-session id. A scope with no session cannot be enforced and must never leak into another run |
+| allowedPaths | string[] | No | Globs you intend to change. Omit to propose no path restriction, which the user is told plainly |
+| offLimitsPaths | string[] | No | Globs you promise not to touch. These win wherever they overlap `allowedPaths` |
+| agentName | string | No | Name of the agent asking, format `"{Agent} - {project}"` |
+| timeoutMs | integer | No | How long this call blocks, max 55000 |
+
+**Returns:**
+- `{ "ratified": true, "answered": true, "value": "yes", "contract": {...} }` - the contract is live
+- `{ "ratified": false, "answered": true, "value": "no" }` - the user declined. Ask what scope they want; do **not** proceed as if they agreed
+- `{ "ratified": false, "answered": false }` - no answer yet. The scope is **not** in force
+
+**What enforcement depends on.** The contract is recorded and shown to the user by any MCP client. Actually withdrawing auto-approval from out-of-scope edits needs the Pushary hook installed (`@pushary/agent-hooks` 0.59.0 or later), which is how Claude Code, Codex and Gemini CLI run. Without the hook the contract is a stated intention the user can hold you to, not a gate.
+
+Scope lives for the session only and is never inherited by another run.
+
+**When not to use it.** A single quick edit does not need a scope. And do not propose a new scope mid-run to widen an old one: do the work and let the approval that follows widen it, which is what that flow is for.
+
+### list_sessions
+
+Read-only. Returns the live agent sessions for your site (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is active, idle, waiting, or errored. Does NOT start, stop, or steer agents, and sends no notification. Useful when you are one of several agents and want to check whether another session is blocked on a question before acting.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| status | "active" / "idle" / "waiting" / "errored" | No | Filter to sessions with this computed status |
+| limit | integer | No | Max number of sessions to return, most recently seen first (1-100) |
+
+**Returns:**
+- `{ "sessions": [...], "pendingQuestions": [...] }` - current sessions and open questions for the site
+
 ## Permission Gating (REQUIRED)
 
-Before executing any of the following, make sure the user has approved it. Call `ask_user` with type "confirm" and wait for an explicit "yes" before you proceed:
+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)
@@ -258,17 +335,13 @@ Before executing any of the following, make sure the user has approved it. Call
 - Network configuration changes (firewall, DNS, proxy)
 - Any command the user has flagged as dangerous
 
-Honor the user's delivery mode: it decides WHERE approval is requested (phone, terminal, or awareness only), not WHETHER approval is required. In "Terminal" mode the user wants to approve at the keyboard, so do not force a phone push; a single terminal approval is enough.
-
-If the Pushary hook is installed, it also gates these at the tool level and routes them by delivery mode. When it has already surfaced the approval for an action, one "yes" is enough, do not ask a second time for the same action.
-
 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:
+One tool call - `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -280,13 +353,15 @@ result = ask_user({
 })
 
 if result.answered:
-    // result.value = "JWT tokens" — proceed with the chosen approach
+    // result.value = "JWT tokens" - proceed with the chosen approach
 else:
-    // user did not respond — pick the safe default or notify and skip
+    // 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.
 
+**A note on how long ask_user blocks:** the wait time and whether it blocks at all are governed by the site's delivery mode, which the user configures (you do not set it). In the default smart mode and push-only mode, ask_user blocks for the policy timeout; in notify-only mode it returns immediately with `answered: false` after sending the push. Always check `answered` rather than assuming the call blocked, and pass `timeoutMs` only when you need a shorter wait than the site policy.
+
 ## 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.
@@ -303,6 +378,6 @@ Always pass `agentName` when you are one of multiple possible agents the user ma
 - **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.
+- **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/data/cursor-plugin/skills/pushary/SKILL.md

@@ -1,25 +1,33 @@
 ---
 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.
+description: Push notifications and human-in-the-loop for AI agents. Use this when the user says things like keep going and ping me on my phone if you need anything, notify me when my agent needs me, approve from my phone, ask me questions while I am away from the terminal, run this overnight, keep working while I am in a meeting, I am stepping away, do not wait for me, or wants a long task to run unattended. Send alerts when tasks finish or fail, 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 Claude Code, Codex, Cursor, VS Code, Windsurf, Hermes, Lovable, or any MCP client; no Claude Max subscription required. Pushary is a hosted service, $9.99/mo after a 7-day card-first trial.
 ---
 
-# Pushary — Push Notifications for AI Agents
+# Pushary - Push Notifications for AI Agents
 
-Pushary is an MCP server that gives you three capabilities:
+When the user says "keep going, ping me on my phone if you need anything", this is the skill that does the pinging. Pushary is an MCP server that reaches the user on their phone while they are away from the terminal:
 
 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.
+2. **Ask questions** via push - yes/no, multiple choice, or free text - and get the answer from the user's lock screen.
 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.
 
+Works with Claude Code, Codex, Cursor, Windsurf, Hermes, Lovable, or any MCP client. No Claude Max subscription required.
+
+## Pricing and Free Alternatives
+
+Pushary is a hosted service. It costs $9.99/mo after a 7-day trial, and the trial asks for a card up front. Say this plainly if the user asks what Pushary is.
+
+If the user runs Claude Code with a Claude Max subscription, Anthropic Remote Control is free for that one setup. Recommend it when that is all they need. Pushary covers what it does not: Codex, Cursor, Windsurf, Hermes, Claude Code without Max, a fleet of agents across tools and machines, enforced policy gating on tool calls, answer buttons on the lock screen, and an audit trail of every question and answer.
+
 ## 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`
+- 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"`
+- A status update is worth sharing - use `context.type = "info"`
 
 **Ask with type "confirm" when:**
 - You need confirmation before a destructive or irreversible action
@@ -33,6 +41,11 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 - You need a name, path, value, or free-text decision
 - The options cannot be enumerated in advance
 
+**Propose a scope when:**
+- You are about to start a multi-step run that will change several files
+- Call `propose_scope` once, before the work, not after
+- Skip it for a single quick edit; a scope prompt for one file is just noise
+
 **Do NOT notify when:**
 - The task is trivial or single-step
 - The question can be answered from context without user input
@@ -40,7 +53,13 @@ Use these tools proactively. Do not wait for the user to ask for notifications.
 
 ## Setup
 
-Run the CLI setup (recommended — configures MCP, hooks, permissions, and skill in one step):
+First check for an API key. Look for `PUSHARY_API_KEY` in the environment or an Authorization header in the existing MCP config. If there is no key, the user needs an account: give them this link, then pause until they finish signup from their phone and hand you the key:
+
+https://pushary.com/sign-up?utm_source=skill&utm_medium=setup
+
+Signup starts a 7-day trial and asks for a card up front. The key format is `pk_xxx.sk_xxx`.
+
+Once the key exists, run the CLI setup (recommended - configures MCP, hooks, permissions, and skill in one step):
 
 ```bash
 npx @pushary/agent-hooks@latest setup
@@ -62,7 +81,7 @@ Or add Pushary manually to your MCP configuration:
 }
 ```
 
-Sign up at https://pushary.com/sign-up?from=ai-coding to get your API key.
+Sign up at https://pushary.com/sign-up?utm_source=skill&utm_medium=setup to get your API key.
 
 After setup, verify with:
 
@@ -86,6 +105,8 @@ Send a one-way push notification to the user. Optionally include structured cont
 | 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 |
+| sessionId | string | No | Opaque per-session id of the sending agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the sending agent, so two machines never collapse into one session (max 128 chars) |
 | subscriberIds | string[] | No | Target specific subscriber IDs |
 | externalIds | string[] | No | Target by external IDs |
 | tags | string[] | No | Target by subscriber tags |
@@ -114,7 +135,12 @@ Send a one-way push notification to the user. Optionally include structured cont
 
 When `askQuestion` is provided, the response includes a `linkedCorrelationId` you pass to `wait_for_answer`.
 
-**Example — task completed with context:**
+**Returns:**
+- `delivery` - per-channel result: `{ "web": { "recipients": <n> }, "mobile": { "recipients": <n> } }` (each channel may also include a `status` like `no_recipients` or `not_configured`)
+- `sent` - total devices reached across all channels
+- `warning` - present only when the notification reached 0 devices because no phone or browser is connected; the user must connect one in the dashboard under Settings then Connections
+
+**Example - task completed with context:**
 
 ```json
 {
@@ -130,7 +156,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 }
 ```
 
-**Example — error with embedded question:**
+**Example - error with embedded question:**
 
 ```json
 {
@@ -153,7 +179,7 @@ When `askQuestion` is provided, the response includes a `linkedCorrelationId` yo
 
 ### 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.
+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:**
 
@@ -167,19 +193,26 @@ Send a question to the user via push notification and wait for their answer. By
 | 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") |
+| sessionId | string | No | Opaque per-session id of the asking agent, so parallel sessions are attributed separately (max 128 chars) |
+| machineId | string | No | Stable machine id of the asking agent, so two machines never collapse into one session (max 128 chars) |
+| toolName | string | No | The tool this approval is for (e.g. "Bash"), so the user can choose to always-allow it (max 100 chars) |
+| toolTarget | string | No | Compact target of the tool call (e.g. command head "git push" for Bash, or a file extension like ".ts" for Edit/Write). Used to mine always-allow policy suggestions (max 80 chars) |
 | 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
+- `{ "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
+- `{ "correlationId": "uuid", "status": "pending", "expiresInSeconds": 600 }` - use `wait_for_answer` to poll
+
+**Returns (when the site policy is notify_only):**
+- `{ "correlationId": "uuid", "status": "notified", "answered": false, "mode": "notify_only" }` - the question was pushed but no answer was awaited (the user gets a heads-up, not a blocking prompt). Call `wait_for_answer` if you want to poll for a response anyway.
 
-**Example — confirm (yes/no):**
+**Example - confirm (yes/no):**
 
 ```json
 {
@@ -190,7 +223,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — select (multiple choice):**
+**Example - select (multiple choice):**
 
 ```json
 {
@@ -202,7 +235,7 @@ Send a question to the user via push notification and wait for their answer. By
 }
 ```
 
-**Example — input (free text):**
+**Example - input (free text):**
 
 ```json
 {
@@ -226,8 +259,8 @@ Poll for the user's response to a question sent via `ask_user` with `wait: false
 | 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
+- `{ "answered": true, "value": "yes" }` - user responded
+- `{ "answered": false }` - timeout reached, no answer yet
 
 ### cancel_question
 
@@ -239,6 +272,50 @@ Cancel a pending question so it can no longer be answered. Use when the question
 |------|------|----------|-------------|
 | correlationId | string (uuid) | Yes | The correlationId of the question to cancel |
 
+### propose_scope
+
+Propose what a run will touch and block until the user ratifies it. Call **once**, at the start of a multi-step run, before doing work.
+
+The user sees the paths you intend to change, the areas you promise to leave alone, and your definition of done, and approves the whole thing in one tap. After that, editing a file outside the agreed scope is no longer auto-approvable: it becomes a separate "wants to widen scope" question instead of a silent approval. Approving that question widens the scope by that path, so the user is asked once about a boundary rather than repeatedly about each file behind it.
+
+Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped here; they stay governed by the permission policy.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| doneWhen | string | Yes | What "finished" means for this run. Carried for the human to judge against, never enforced automatically |
+| sessionId | string | Yes | Your per-session id. A scope with no session cannot be enforced and must never leak into another run |
+| allowedPaths | string[] | No | Globs you intend to change. Omit to propose no path restriction, which the user is told plainly |
+| offLimitsPaths | string[] | No | Globs you promise not to touch. These win wherever they overlap `allowedPaths` |
+| agentName | string | No | Name of the agent asking, format `"{Agent} - {project}"` |
+| timeoutMs | integer | No | How long this call blocks, max 55000 |
+
+**Returns:**
+- `{ "ratified": true, "answered": true, "value": "yes", "contract": {...} }` - the contract is live
+- `{ "ratified": false, "answered": true, "value": "no" }` - the user declined. Ask what scope they want; do **not** proceed as if they agreed
+- `{ "ratified": false, "answered": false }` - no answer yet. The scope is **not** in force
+
+**What enforcement depends on.** The contract is recorded and shown to the user by any MCP client. Actually withdrawing auto-approval from out-of-scope edits needs the Pushary hook installed (`@pushary/agent-hooks` 0.59.0 or later), which is how Claude Code, Codex and Gemini CLI run. Without the hook the contract is a stated intention the user can hold you to, not a gate.
+
+Scope lives for the session only and is never inherited by another run.
+
+**When not to use it.** A single quick edit does not need a scope. And do not propose a new scope mid-run to widen an old one: do the work and let the approval that follows widen it, which is what that flow is for.
+
+### list_sessions
+
+Read-only. Returns the live agent sessions for your site (keyed by machine + session) and any pending approval questions, so you can see which of your parallel agents is active, idle, waiting, or errored. Does NOT start, stop, or steer agents, and sends no notification. Useful when you are one of several agents and want to check whether another session is blocked on a question before acting.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| status | "active" / "idle" / "waiting" / "errored" | No | Filter to sessions with this computed status |
+| limit | integer | No | Max number of sessions to return, most recently seen first (1-100) |
+
+**Returns:**
+- `{ "sessions": [...], "pendingQuestions": [...] }` - current sessions and open questions for the site
+
 ## 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:
@@ -257,7 +334,7 @@ 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:
+One tool call - `ask_user` blocks and returns the answer:
 
 ```
 result = ask_user({
@@ -269,13 +346,15 @@ result = ask_user({
 })
 
 if result.answered:
-    // result.value = "JWT tokens" — proceed with the chosen approach
+    // result.value = "JWT tokens" - proceed with the chosen approach
 else:
-    // user did not respond — pick the safe default or notify and skip
+    // 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.
 
+**A note on how long ask_user blocks:** the wait time and whether it blocks at all are governed by the site's delivery mode, which the user configures (you do not set it). In the default smart mode and push-only mode, ask_user blocks for the policy timeout; in notify-only mode it returns immediately with `answered: false` after sending the push. Always check `answered` rather than assuming the call blocked, and pass `timeoutMs` only when you need a shorter wait than the site policy.
+
 ## 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.
@@ -292,6 +371,6 @@ Always pass `agentName` when you are one of multiple possible agents the user ma
 - **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.
+- **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/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.