claude-remote-approver 0.5.1 → 0.6.0

package/README.md

@@ -21,22 +21,36 @@ cli.mjs hook
   │
   ├──POST──▶ ntfy.sh/<topic>          ──push──▶  Phone (ntfy app)
   │                                                 │
-  │                                           Approve / Deny tap
+  │                                     Approve / Always Allow / Deny tap
   │                                                 │
   └──SSE───▶ ntfy.sh/<topic>-response  ◀──POST──┘
   │
-  │  stdout JSON: { "behavior": "allow" } or { "behavior": "deny" }
+  │  stdout JSON: allow / deny / ask (CLI fallback)
   ▼
 Claude Code continues or stops
 ```
 
 1. Claude Code invokes the hook, piping the tool request as JSON to stdin.
-2. `cli.mjs hook` sends a notification to your ntfy topic with **Approve** and **Deny** action buttons.
+2. `cli.mjs hook` sends a notification to your ntfy topic with **Approve**, **Always Allow**, and **Deny** action buttons.
 3. The hook subscribes to a response topic (`<topic>-response`) via server-sent events.
 4. When you tap a button on your phone, ntfy.sh publishes your decision to the response topic.
-5. The hook reads the decision, writes `{"behavior":"allow"}` or `{"behavior":"deny"}` to stdout, and exits.
+5. The hook reads the decision and writes `{"behavior":"allow"}` or `{"behavior":"deny"}` to stdout. If the notification fails or times out, the hook returns `{"behavior":"ask"}` so Claude Code falls back to the CLI prompt.
 6. Claude Code proceeds accordingly.
 
+### AskUserQuestion support
+
+When Claude Code calls the `AskUserQuestion` tool, the hook sends the question to your phone as a notification. Each option appears as an action button you can tap. If the question has more than 3 options, they are split across multiple notifications. If no response is received before the timeout, the hook falls back to the CLI prompt so you can answer at your terminal.
+
+### Always Allow
+
+When Claude Code sends a `permission_suggestions` field with the hook request (indicating the tool can be auto-approved in future), the notification shows three buttons: **Approve**, **Always Allow**, and **Deny**.
+
+- **Approve** -- Allow this one request.
+- **Always Allow** -- Allow this request and tell Claude Code to auto-approve this tool in future sessions. Claude Code adds the permission rule to its settings so it won't ask again.
+- **Deny** -- Reject this request.
+
+If the hook request does not include `permission_suggestions`, only the standard **Approve** and **Deny** buttons are shown.
+
 ## Quick Start
 
 ```bash
@@ -179,7 +193,7 @@ Config file location: `~/.claude-remote-approver.json`
 |---|---|---|---|
 | `topic` | `string` | `""` | Your unique ntfy topic. Generated by `setup`. |
 | `ntfyServer` | `string` | `"https://ntfy.sh"` | The ntfy server URL. Change this if you self-host. |
-| `timeout` | `number` | `120` | Seconds to wait for a response before auto-denying. |
+| `timeout` | `number` | `120` | Seconds to wait for a response before falling back to CLI. |
 | `planTimeout` | `number` | `300` | Seconds to wait for ExitPlanMode (plan approval) responses. Plan reviews need more reading time. |
 | `autoApprove` | `string[]` | `[]` | Reserved for future use. |
 | `autoDeny` | `string[]` | `[]` | Reserved for future use. |
@@ -225,7 +239,7 @@ The public ntfy.sh server is convenient but means your permission request detail
 
 ### Timeout behavior
 
-If no response is received within the configured timeout (default: 120 seconds), the hook automatically **denies** the request. This fail-closed design ensures Claude Code does not proceed without explicit approval.
+If no response is received within the configured timeout (default: 120 seconds), the hook falls back to the **CLI prompt** (`ask`), so you can still respond at your terminal.
 
 ## Disclaimer
 
@@ -234,7 +248,7 @@ If no response is received within the configured timeout (default: 120 seconds),
 The authors are not responsible for any damages or losses arising from the use of this tool, including but not limited to:
 
 - Accidental approval of dangerous commands (e.g., mistapping Approve on your phone)
-- Unintended denial of safe commands (e.g., timeout, network issues)
+- Unintended CLI fallback when away from terminal (e.g., timeout, network issues)
 - Security breaches if the topic name is compromised
 
 **Not a substitute for careful review.** The push notification shows the tool name and a brief summary, but not the full context of what Claude Code is doing. Always review what you are approving.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-remote-approver",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Approve or deny Claude Code permission prompts remotely from your phone via ntfy.sh",
   "type": "module",
   "bin": {

package/src/hook.mjs

@@ -6,18 +6,23 @@ import { DEFAULT_CONFIG } from "./config.mjs";
 export const ASK = Object.freeze({ hookSpecificOutput: Object.freeze({ hookEventName: "PermissionRequest", decision: Object.freeze({ behavior: "ask" }) }) });
 const DENY = Object.freeze({ hookSpecificOutput: Object.freeze({ hookEventName: "PermissionRequest", decision: Object.freeze({ behavior: "deny" }) }) });
 const MAX_RETRIES = 3;
+export const RETRY_DELAY_MS = 1000;
+/** @internal Replaceable delay for testing. Do not use outside of tests. */
+export const _internal = { delay: ms => new Promise(r => setTimeout(r, ms)) };
 
 /**
- * Build ntfy action buttons for Approve / Deny.
+ * Build ntfy action buttons for Approve / Deny (and optionally Always Allow).
  *
  * @param {string} server - ntfy server URL
  * @param {string} topic - ntfy topic
  * @param {string} requestId - Unique request identifier
- * @returns {Array<object>} Array of 2 action objects
+ * @param {object} [options] - Optional settings
+ * @param {string[]} [options.permissionSuggestions] - When non-empty, adds an "Always Allow" button
+ * @returns {Array<object>} Array of action objects
  */
-export function buildActions(server, topic, requestId) {
+export function buildActions(server, topic, requestId, { permissionSuggestions } = {}) {
   const url = `${server}/${topic}-response`;
-  return [
+  const actions = [
     {
       action: "http",
       label: "Approve",
@@ -33,10 +38,21 @@ export function buildActions(server, topic, requestId) {
       method: "POST",
     },
   ];
+  if (permissionSuggestions?.length > 0) {
+    actions.splice(1, 0, {
+      action: "http",
+      label: "Always Allow",
+      url,
+      body: JSON.stringify({ requestId, approved: true, alwaysAllow: true }),
+      method: "POST",
+    });
+  }
+  return actions;
 }
 
 /**
  * Send with retry, returning null on exhausted retries.
+ * Uses linear backoff: delay = RETRY_DELAY_MS * attempt (1s, 2s, …).
  */
 export async function sendWithRetry(sendFn, params) {
   for (let i = 0; i < MAX_RETRIES; i++) {
@@ -47,6 +63,7 @@ export async function sendWithRetry(sendFn, params) {
         console.error(`[claude-remote-approver] Notification failed after ${MAX_RETRIES} attempts:`, err.message, "— Falling back to CLI.");
         return null;
       }
+      await _internal.delay(RETRY_DELAY_MS * (i + 1));
     }
   }
   return null;
@@ -189,7 +206,9 @@ export async function processHook(input, { loadConfig, sendNotification, waitFor
 
   const requestId = crypto.randomUUID();
   const { title, message } = formatToolInfo(input);
-  const actions = buildActions(config.ntfyServer, config.topic, requestId);
+  const actions = buildActions(config.ntfyServer, config.topic, requestId, {
+    permissionSuggestions: input.permission_suggestions,
+  });
 
   const sent = await sendWithRetry(sendNotification, {
     server: config.ntfyServer,
@@ -225,5 +244,9 @@ export async function processHook(input, { loadConfig, sendNotification, waitFor
     return ASK;
   }
   if (response.approved === false) return DENY;
-  return { hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "allow" } } };
+  const decision = { behavior: "allow" };
+  if (response.alwaysAllow === true && input.permission_suggestions?.length > 0) {
+    decision.updatedPermissions = input.permission_suggestions;
+  }
+  return { hookSpecificOutput: { hookEventName: "PermissionRequest", decision } };
 }

package/src/ntfy.mjs

@@ -73,7 +73,7 @@ export async function waitForResponse({ server, topic, requestId, timeout }) {
               if (typeof parsed.answer === 'string') {
                 return { answer: parsed.answer };
               }
-              return { approved: parsed.approved };
+              return { approved: parsed.approved, alwaysAllow: parsed.alwaysAllow === true };
             }
           } catch {
             // skip non-JSON lines