@pushary/agent-hooks 0.87.0 → 0.87.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.87.1
+
+### Unanswered approvals hand off once and fail closed
+
+The installed agent instructions now distinguish a live timeout from cancelled,
+missing and unavailable questions. They poll once, cancel before moving the
+decision into the current client, reconcile the cancellation race once, and stop
+when Pushary cannot safely fence the question state.
+
 ## 0.86.0
 
 ### Approving a plan from your phone

package/data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pushary
-version: 0.9.2
+version: 0.9.3
 description: Push notifications and human-in-the-loop for AI agents. Use this whenever a running agent needs a human and nobody is at the terminal, such as before an irreversible or destructive action, before spending money, deploying, force-pushing or deleting, when blocked on a decision outside your authority, when running unattended and you hit a genuine ambiguity, when another skill's workflow says to confirm with the user, and when a long task finishes or fails with nobody watching. Also use it 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. Every question and answer is recorded, so an unattended run stays reviewable afterwards. 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 3-day card-first trial.
 metadata:
   hermes:
@@ -202,9 +202,20 @@ Send a question to the user via push notification and wait for their answer. By
 
 Always read `answered` rather than assuming the call blocked. It comes back false
 in three different situations that mean different things: the wait timed out and
-the question is still live (`timedOut`), the site policy is notify_only so nothing
-was awaited (`status: "notified"`), or you passed `wait: false` yourself
-(`status: "pending"`). All three leave a `correlationId` you can poll.
+the question is still live (`timedOut`), the site policy is notify_only so the
+decision belongs in the current client (`status: "notified"`), or you passed
+`wait: false` yourself (`status: "pending"`). Follow `handoffAction` when present,
+otherwise `nextAction`.
+
+For backward compatibility, `nextAction` keeps its original two values. A live timeout from `ask_user` says
+`wait_for_answer`; poll once with `timeoutMs: 55000`. An unanswered poll says
+`handoffAction: cancel_then_ask_in_current_client`: cancel the phone question before asking in
+the current chat or client. If cancellation returns `handoffAction: "stop"`, stop.
+Otherwise, if cancellation returns false, poll once for 1 second
+and honor any answer that won the race. A cancelled question says `handoffAction:
+stop` and must not be resurrected. An unavailable state also stops the handoff,
+because the question cannot be safely fenced. Expired and missing questions are
+not live timeouts.
 
 Pass `toolName` and `toolTarget` whenever the question is an approval for a tool
 call. They are what let the user turn a repeated approval into an always-allow
@@ -249,10 +260,12 @@ rule, so an approval you label once is an approval they never see again.
 
 Poll for the user's response to a question sent via `ask_user` with `wait: false`, or to one that timed out. Not needed when using the default blocking mode.
 
-A single call waits at most 55 seconds but the question stays answerable for 10
-minutes, so one empty return is not a refusal. Retry with the same
-`correlationId` up to three times at `timeoutMs: 55000` before treating it as
-unanswered.
+A single call waits at most 55 seconds. Use it once after a live `ask_user`
+timeout. If it returns `answered: false`, follow `handoffAction` when present,
+otherwise `nextAction`: ask in the current chat or client only after cancelling a still-pending phone question. If the
+cancellation loses a race, poll once for 1 second and honor the phone answer
+instead. Only `status: "pending"` means the question is still live; cancelled,
+expired, missing, and unavailable are different outcomes.
 
 ### cancel_question
 
@@ -273,6 +286,13 @@ Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped he
 the user declined: ask what scope they want, and do **not** proceed as if they had
 agreed. Not answered means the scope is simply not in force.
 
+An unanswered proposal returns its `correlationId`. Poll it once; a late phone
+yes ratifies the exact stored proposal. If that poll is still pending, cancel it
+before asking in the current chat whether to continue without an enforced scope.
+If cancellation returns `handoffAction: "stop"`, stop. Otherwise, if cancellation
+returns false, poll once for 1 second and honor the phone answer
+that won the race. A yes in chat is not a server-ratified scope.
+
 Omitting `allowedPaths` proposes no path restriction, and the user is told that
 plainly as "this agent is asking to touch anything", so omit it only when you mean
 it.
@@ -303,7 +323,7 @@ Before executing any of the following, you MUST call `ask_user` with type "confi
 - 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.
+If `ask_user` returns `answered: false`, do not execute yet and do not call the task blocked. Follow `handoffAction` when present, otherwise `nextAction`: poll once, then cancel a live phone question before asking in the current client. Execute only after an explicit "yes" from the winning surface.
 
 This is not optional. Treat it as a hard constraint, not a suggestion.
 
@@ -323,10 +343,10 @@ result = ask_user({
 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
+    // follow result.handoffAction when present, otherwise result.nextAction
 ```
 
-If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
+If the user answers in chat before the push response arrives, call `cancel_question` before acting. If it returns `handoffAction: "stop"`, stop. Otherwise, if it returns false, poll once for 1 second and honor any phone answer that won the race.
 
 **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.
 

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

@@ -2,7 +2,7 @@
   "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",
+  "version": "0.2.0",
   "author": { "name": "Pushary", "email": "business@pushary.com" },
   "homepage": "https://pushary.com",
   "repository": "https://github.com/Pushary/cursor-plugin",

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

@@ -16,9 +16,9 @@ When Pushary is connected, it is your channel for reaching the user. Any time yo
 - 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.
+`ask_user` blocks and returns `{ answered, value, nextAction, handoffAction }`. Always set `context` to one line on what you are doing, and set `agentName` to "Cursor - {project}". If `answered` is false, follow `handoffAction` when present, otherwise `nextAction`: poll once when instructed, then cancel a live phone question before asking in the current chat. 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.
+If the user answers in the chat before the push comes back, call `cancel_question` with the correlationId before acting. If cancellation returns `handoffAction: "stop"`, stop. Otherwise, if cancellation returns false, poll once for 1 second and honor any phone answer that won the race.
 
 ## Notify the user
 

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

@@ -195,9 +195,20 @@ Send a question to the user via push notification and wait for their answer. By
 
 Always read `answered` rather than assuming the call blocked. It comes back false
 in three different situations that mean different things: the wait timed out and
-the question is still live (`timedOut`), the site policy is notify_only so nothing
-was awaited (`status: "notified"`), or you passed `wait: false` yourself
-(`status: "pending"`). All three leave a `correlationId` you can poll.
+the question is still live (`timedOut`), the site policy is notify_only so the
+decision belongs in the current client (`status: "notified"`), or you passed
+`wait: false` yourself (`status: "pending"`). Follow `handoffAction` when present,
+otherwise `nextAction`.
+
+For backward compatibility, `nextAction` keeps its original two values. A live timeout from `ask_user` says
+`wait_for_answer`; poll once with `timeoutMs: 55000`. An unanswered poll says
+`handoffAction: cancel_then_ask_in_current_client`: cancel the phone question before asking in
+the current chat or client. If cancellation returns `handoffAction: "stop"`, stop.
+Otherwise, if cancellation returns false, poll once for 1 second
+and honor any answer that won the race. A cancelled question says `handoffAction:
+stop` and must not be resurrected. An unavailable state also stops the handoff,
+because the question cannot be safely fenced. Expired and missing questions are
+not live timeouts.
 
 Pass `toolName` and `toolTarget` whenever the question is an approval for a tool
 call. They are what let the user turn a repeated approval into an always-allow
@@ -242,10 +253,12 @@ rule, so an approval you label once is an approval they never see again.
 
 Poll for the user's response to a question sent via `ask_user` with `wait: false`, or to one that timed out. Not needed when using the default blocking mode.
 
-A single call waits at most 55 seconds but the question stays answerable for 10
-minutes, so one empty return is not a refusal. Retry with the same
-`correlationId` up to three times at `timeoutMs: 55000` before treating it as
-unanswered.
+A single call waits at most 55 seconds. Use it once after a live `ask_user`
+timeout. If it returns `answered: false`, follow `handoffAction` when present,
+otherwise `nextAction`: ask in the current chat or client only after cancelling a still-pending phone question. If the
+cancellation loses a race, poll once for 1 second and honor the phone answer
+instead. Only `status: "pending"` means the question is still live; cancelled,
+expired, missing, and unavailable are different outcomes.
 
 ### cancel_question
 
@@ -266,6 +279,13 @@ Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped he
 the user declined: ask what scope they want, and do **not** proceed as if they had
 agreed. Not answered means the scope is simply not in force.
 
+An unanswered proposal returns its `correlationId`. Poll it once; a late phone
+yes ratifies the exact stored proposal. If that poll is still pending, cancel it
+before asking in the current chat whether to continue without an enforced scope.
+If cancellation returns `handoffAction: "stop"`, stop. Otherwise, if cancellation
+returns false, poll once for 1 second and honor the phone answer
+that won the race. A yes in chat is not a server-ratified scope.
+
 Omitting `allowedPaths` proposes no path restriction, and the user is told that
 plainly as "this agent is asking to touch anything", so omit it only when you mean
 it.
@@ -296,7 +316,7 @@ Before executing any of the following, you MUST call `ask_user` with type "confi
 - 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.
+If `ask_user` returns `answered: false`, do not execute yet and do not call the task blocked. Follow `handoffAction` when present, otherwise `nextAction`: poll once, then cancel a live phone question before asking in the current client. Execute only after an explicit "yes" from the winning surface.
 
 This is not optional. Treat it as a hard constraint, not a suggestion.
 
@@ -316,10 +336,10 @@ result = ask_user({
 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
+    // follow result.handoffAction when present, otherwise result.nextAction
 ```
 
-If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
+If the user answers in chat before the push response arrives, call `cancel_question` before acting. If it returns `handoffAction: "stop"`, stop. Otherwise, if it returns false, poll once for 1 second and honor any phone answer that won the race.
 
 **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.
 

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

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.2.0",
   "author": {
     "name": "Pushary",
     "email": "business@pushary.com",

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

@@ -195,9 +195,20 @@ Send a question to the user via push notification and wait for their answer. By
 
 Always read `answered` rather than assuming the call blocked. It comes back false
 in three different situations that mean different things: the wait timed out and
-the question is still live (`timedOut`), the site policy is notify_only so nothing
-was awaited (`status: "notified"`), or you passed `wait: false` yourself
-(`status: "pending"`). All three leave a `correlationId` you can poll.
+the question is still live (`timedOut`), the site policy is notify_only so the
+decision belongs in the current client (`status: "notified"`), or you passed
+`wait: false` yourself (`status: "pending"`). Follow `handoffAction` when present,
+otherwise `nextAction`.
+
+For backward compatibility, `nextAction` keeps its original two values. A live timeout from `ask_user` says
+`wait_for_answer`; poll once with `timeoutMs: 55000`. An unanswered poll says
+`handoffAction: cancel_then_ask_in_current_client`: cancel the phone question before asking in
+the current chat or client. If cancellation returns `handoffAction: "stop"`, stop.
+Otherwise, if cancellation returns false, poll once for 1 second
+and honor any answer that won the race. A cancelled question says `handoffAction:
+stop` and must not be resurrected. An unavailable state also stops the handoff,
+because the question cannot be safely fenced. Expired and missing questions are
+not live timeouts.
 
 Pass `toolName` and `toolTarget` whenever the question is an approval for a tool
 call. They are what let the user turn a repeated approval into an always-allow
@@ -242,10 +253,12 @@ rule, so an approval you label once is an approval they never see again.
 
 Poll for the user's response to a question sent via `ask_user` with `wait: false`, or to one that timed out. Not needed when using the default blocking mode.
 
-A single call waits at most 55 seconds but the question stays answerable for 10
-minutes, so one empty return is not a refusal. Retry with the same
-`correlationId` up to three times at `timeoutMs: 55000` before treating it as
-unanswered.
+A single call waits at most 55 seconds. Use it once after a live `ask_user`
+timeout. If it returns `answered: false`, follow `handoffAction` when present,
+otherwise `nextAction`: ask in the current chat or client only after cancelling a still-pending phone question. If the
+cancellation loses a race, poll once for 1 second and honor the phone answer
+instead. Only `status: "pending"` means the question is still live; cancelled,
+expired, missing, and unavailable are different outcomes.
 
 ### cancel_question
 
@@ -266,6 +279,13 @@ Use glob syntax (`src/**`, `**/*.test.ts`). Shell commands are **not** scoped he
 the user declined: ask what scope they want, and do **not** proceed as if they had
 agreed. Not answered means the scope is simply not in force.
 
+An unanswered proposal returns its `correlationId`. Poll it once; a late phone
+yes ratifies the exact stored proposal. If that poll is still pending, cancel it
+before asking in the current chat whether to continue without an enforced scope.
+If cancellation returns `handoffAction: "stop"`, stop. Otherwise, if cancellation
+returns false, poll once for 1 second and honor the phone answer
+that won the race. A yes in chat is not a server-ratified scope.
+
 Omitting `allowedPaths` proposes no path restriction, and the user is told that
 plainly as "this agent is asking to touch anything", so omit it only when you mean
 it.
@@ -296,7 +316,7 @@ Before executing any of the following, you MUST call `ask_user` with type "confi
 - 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.
+If `ask_user` returns `answered: false`, do not execute yet and do not call the task blocked. Follow `handoffAction` when present, otherwise `nextAction`: poll once, then cancel a live phone question before asking in the current client. Execute only after an explicit "yes" from the winning surface.
 
 This is not optional. Treat it as a hard constraint, not a suggestion.
 
@@ -316,10 +336,10 @@ result = ask_user({
 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
+    // follow result.handoffAction when present, otherwise result.nextAction
 ```
 
-If the user answers in chat before the push response arrives, continue normally and call `cancel_question` with the `correlationId` to clean up.
+If the user answers in chat before the push response arrives, call `cancel_question` before acting. If it returns `handoffAction: "stop"`, stop. Otherwise, if it returns false, poll once for 1 second and honor any phone answer that won the race.
 
 **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.
 

package/dist/bin/pushary-clean.js

@@ -8,7 +8,7 @@ import {
   shortenHome,
   unregisterPluginLocation,
   vscodeSettingsTargets
-} from "../chunk-IWL5LWIE.js";
+} from "../chunk-LT2VLPUK.js";
 import {
   removeGeminiSettings
 } from "../chunk-ZZE6FN7T.js";

package/dist/bin/pushary-doctor.js

@@ -18,7 +18,7 @@ import {
   isDetected,
   isPluginRegistered,
   vscodeSettingsTargets
-} from "../chunk-IWL5LWIE.js";
+} from "../chunk-LT2VLPUK.js";
 import {
   GEMINI_HOOK_BINARY,
   hasGeminiHooks,

package/dist/bin/pushary-setup.js

@@ -31,7 +31,7 @@ import {
   shortenHome,
   vscodeSettingsTargets,
   writeInstructionBlock
-} from "../chunk-IWL5LWIE.js";
+} from "../chunk-LT2VLPUK.js";
 import {
   GEMINI_HOOK_BINARY,
   addGeminiHooks,

package/dist/{chunk-IWL5LWIE.js → chunk-LT2VLPUK.js}

@@ -259,7 +259,7 @@ You have Pushary MCP tools that reach the user on their phone. Use them proactiv
 - Use \`cancel_question\` to retract a pending question once it is no longer needed.
 - Respect the user's Pushary delivery mode: it decides where an approval is surfaced (phone, terminal, or awareness only), not whether it is required. In Terminal mode do not expect a phone answer; the approval waits in the terminal. If the Pushary hook already gated an action, a single approval is enough, do not ask again.
 
-Pass \`agentName\` as "${label} - <project folder name>" so the user knows which session is asking. If a question times out with no answer, retry once with a longer timeout before falling back to asking in the terminal.`;
+Pass \`agentName\` as "${label} - <project folder name>" so the user knows which session is asking. If a question times out, follow \`handoffAction\` when present, otherwise \`nextAction\`: poll once, then cancel a live phone question before asking in the current client. If cancellation returns \`handoffAction: "stop"\`, stop. Otherwise, if cancellation returns false, poll once for 1 second and honor the answer that won the race.`;
 var renderAgentInstructions = (label) => instructionBody(label);
 var KEYLESS_FALLBACK_LINE = "This repo uses Pushary phone approvals. Your teammates get agent questions on their lock screens; you do not have a key yet, so questions will fall back to the terminal. Get your own key (3-day trial): https://pushary.com/sign-up?utm_source=agents-md&utm_medium=teammate";
 var renderProjectAgentInstructions = (label) => `${instructionBody(label)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushary/agent-hooks",
-  "version": "0.87.0",
+  "version": "0.87.1",
   "description": "Permission hooks for AI coding agents: route tool approvals through Pushary push notifications",
   "keywords": [
     "pushary",