@zeph-to/mcp-server 2.1.0 → 2.3.0

package/README.md

@@ -4,6 +4,7 @@
 [![downloads](https://img.shields.io/npm/dm/@zeph-to/mcp-server.svg)](https://www.npmjs.com/package/@zeph-to/mcp-server)
 [![node](https://img.shields.io/node/v/@zeph-to/mcp-server.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@zeph-to/mcp-server.svg)](./LICENSE)
+[![docs](https://img.shields.io/badge/docs-docs.zeph.to-1f6feb)](https://docs.zeph.to)
 
 **Your agent calls `zeph_ask`; the question lands on your phone as buttons + a text field; your reply comes back into the same tool call and the agent keeps going.**
 
@@ -16,6 +17,8 @@ Zeph's MCP server is the agent side of that round trip — plus one-way notifica
 
 Part of the Zeph toolchain: [`@zeph-to/cli`](https://github.com/zeph-to/cli) (installer, push CLI, tmux remote control) · [`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin bundling this server) · the [Zeph app](https://zeph.to) on your phone.
 
+> **New here?** [docs.zeph.to](https://docs.zeph.to) walks the whole setup — one command on your machine, the app on your phone, and a restart. The reference below assumes that is already done.
+
 ## Setup
 
 The easiest way to set up for all agents at once:
@@ -70,7 +73,7 @@ e.g. a second account:
 | `ZEPH_WS_URL` | No | WebSocket endpoint for the hook-response fast path — `zeph_ask`/`zeph_prompt`/`zeph_input` answers arrive the moment the user submits them instead of on the next poll. Falls back to pure polling when unset. Also read from `wsUrl` in `~/.zeph/config.json` |
 | `ZEPH_DISABLE_SESSION_CACHE` | No | Set to `1`/`true` to skip writing the session-id handoff file under `~/.cache/zeph/`. Useful for read-only filesystems, ephemeral CI runners, or sandboxed envs that audit filesystem writes. The plugin's stop hook still works without it (transcript-path UUID extraction is the primary path; the cache is a fallback for older Claude Code versions). |
 | `ZEPH_SESSION_ID` | No | Override the session id attached to pushes (grouping in the app). Auto-detected from the newest Claude Code transcript when unset |
-| `ZEPH_DISABLE_ENCRYPTION` | No | Set to `1`/`true` to force E2E-style push encryption off, even when the account has keys. Useful while cleaning up legacy key state |
+| `ZEPH_DISABLE_ENCRYPTION` | No | Set to `1`/`true` to force push encryption off even when the account has it enabled. A local override for debugging what the server actually received — encryption is already off unless the account opted in (see [Encryption](#encryption)) |
 
 \* If env vars are not set, the server reads from `~/.zeph/config.json` (created by `zeph install`). Unresolved `${...}` interpolations are also treated as unset.
 
@@ -184,7 +187,9 @@ Returns: `{ actionId: "yes", timedOut: false }`
 
 ### zeph_ask
 
-Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.
+Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. Blocks until response or timeout.
+
+`actions` is the steering surface: pass 2–4 buttons on nearly every ask (the next-step candidates plus a safe Done-like `fallback`) and leave it out only when the answer is inherently free-form text — a bare text box on a "done — what next?" ask gives the phone nothing to tap.
 
 Requires `ZEPH_HOOK_ID`.
 
@@ -339,12 +344,12 @@ Create an API key with the **MCP** preset in Settings > API Keys for the correct
 
 ## Encryption
 
-Push bodies and file attachments are encrypted with AES-256-GCM. This server holds its own ECDH P-256 keypair, generated on first use and stored in `~/.config/zeph/device-keys.json` — the private half never leaves the machine. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
+End-to-end encryption is **off by default** and turning it on needs Zeph Pro. The switch is in the app under Settings → E2E Encryption; until you flip it, every push leaves this server in plaintext. If the account later loses Pro the server answers `PRO_REQUIRED` and this one drops back to plaintext for the rest of the process. No configuration either way — but the opt-in is read **once at startup**, so turning it on while this server is running takes effect only after a restart.
 
-Toggle encryption in the Zeph app (Settings → Encryption); when it is off, pushes go out as plaintext. No configuration needed. The opt-in is read once at startup, so **turning it on while this server is running takes effect only after a restart.**
+With it on, push bodies and file attachments are encrypted with AES-256-GCM. This server holds its own ECDH P-256 keypair, generated on first use and stored in `~/.config/zeph/device-keys.json` — the private half never leaves the machine, and the backend stores public keys only and rejects a private-key upload. Each push is encrypted once, and its AES key is wrapped separately for every device on your account using ECDH against that device's public key.
 
 **Threat model:** against a passive backend — a leaked snapshot, an operator reading the table — the stored ciphertext and wrapped keys are useless, so push contents stay private. Three limits worth knowing:
-- **No protection from an active malicious operator.** Recipient public keys come from `GET /devices` on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. Closing this needs out-of-band device verification (ADR-0007 Phase 4, not built).
+- **No protection from an active malicious operator.** Recipient public keys come from `GET /devices` on that same server, unsigned and unpinned. A backend that injects a device record carrying its own key gets the message key wrapped for it, and reads everything. The Zeph app ships the counter-measure — compare device fingerprints, mark a device verified, and strict mode then wraps only for verified devices — but it defaults off, its verified list is per browser profile, and this server does not consult it: `selectRecipients` asks only whether a device has a public key, and whether that key is the legacy account-wide one (ADR-0007 Phase 4).
 - **No forward secrecy.** The ECDH secret for a given sender/device pair is static, so compromising either private key opens every past push wrapped for that pair.
 - **`senderPublicKey` is unsigned**, so a swapped one makes a push undecryptable — that direction fails closed rather than leaking.
 

package/dist/config.d.ts

@@ -16,6 +16,15 @@ export interface McpServerConfig {
     /** Last path segment of the project directory — prefixed onto push titles. */
     projectName: string;
 }
+/** The project directory the agent runs in, across supported agents. */
+/**
+ * The key every per-project zeph file is named by. Shelling out to `cksum`
+ * (rather than a pure-JS CRC) is what guarantees it matches the files the bash
+ * hooks have already written — they key off `printf '%s' "$dir" | cksum`. Null
+ * when `cksum` is unavailable, which means no per-project file can be resolved.
+ */
+export declare const projectHash: (dir: string) => string | null;
+export declare const detectProjectDir: () => string;
 /**
  * Prefix a push title with the project name so the device feed stays
  * scannable — "zeph · Build finished" instead of a bare "Build finished".

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAiBD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAuGF,eAAO,MAAM,UAAU,QAAO,eAiC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,eAAe;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;0EACsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;uCAGmC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAC;CACvB;AAID,wEAAwE;AACxE;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAMlD,CAAC;AAEF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,aAAa,MAAM,EAAE,OAAO,MAAM,KAAG,MAGpE,CAAC;AAwGF,eAAO,MAAM,UAAU,QAAO,eAiC7B,CAAC;AA4BF;;;;;sEAKsE;AACtE,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = void 0;
+exports.listenerDeviceId = exports.loadConfig = exports.formatPushTitle = exports.detectProjectDir = exports.projectHash = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const crypto_1 = require("crypto");
@@ -9,6 +9,21 @@ const path_1 = require("path");
 const DEFAULT_BASE_URL = 'https://api.zeph.to/v1';
 const PROJECT_DIR_ENV_KEYS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
 /** The project directory the agent runs in, across supported agents. */
+/**
+ * The key every per-project zeph file is named by. Shelling out to `cksum`
+ * (rather than a pure-JS CRC) is what guarantees it matches the files the bash
+ * hooks have already written — they key off `printf '%s' "$dir" | cksum`. Null
+ * when `cksum` is unavailable, which means no per-project file can be resolved.
+ */
+const projectHash = (dir) => {
+    try {
+        return (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' }).split(' ')[0] || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.projectHash = projectHash;
 const detectProjectDir = () => {
     for (const key of PROJECT_DIR_ENV_KEYS) {
         const val = process.env[key];
@@ -17,6 +32,7 @@ const detectProjectDir = () => {
     }
     return process.cwd();
 };
+exports.detectProjectDir = detectProjectDir;
 /** Last path segment of a directory: "/Users/me/code/zeph" -> "zeph". */
 const projectNameFromDir = (dir) => dir.split('/').filter(Boolean).pop() ?? 'project';
 /**
@@ -106,7 +122,9 @@ const writeSessionCache = (sessionId, projectDir) => {
     if (envIsTrue('ZEPH_DISABLE_SESSION_CACHE'))
         return;
     try {
-        const hash = (0, child_process_1.execFileSync)('cksum', { input: projectDir, encoding: 'utf-8' }).split(' ')[0];
+        const hash = (0, exports.projectHash)(projectDir);
+        if (!hash)
+            return;
         const cacheDir = (0, path_1.join)(process.env.XDG_CACHE_HOME ?? (0, path_1.join)((0, os_1.homedir)(), '.cache'), 'zeph');
         (0, fs_1.mkdirSync)(cacheDir, { recursive: true, mode: 0o700 });
         const cachePath = (0, path_1.join)(cacheDir, `session-${hash}`);
@@ -130,7 +148,7 @@ const loadConfig = () => {
     if (!apiKey) {
         throw new Error('ZEPH_API_KEY not found. Run "npx @zeph-to/cli install" or set ZEPH_API_KEY env var.');
     }
-    const projectDir = detectProjectDir();
+    const projectDir = (0, exports.detectProjectDir)();
     // Claude Code names the running session outright; take it over the
     // transcript scan, which picks the newest file in the project directory and
     // so returns a sibling agent's id whenever two run in one project — the

package/dist/remote-state.d.ts

@@ -0,0 +1,34 @@
+/**
+ * True when this button ends the session. Case-insensitive by contract — the
+ * rules have always said so, but until now nothing enforced it, so a skill
+ * emitting `Done` would have read as a non-exit answer and left the user in
+ * REMOTE for the whole TTL.
+ */
+export declare const isSessionExitId: (actionId: string) => boolean;
+/**
+ * What a `zeph_ask` outcome does to the mode.
+ *
+ * - **exit** — a Done-like id, whether the user tapped it or a timeout
+ *   resolved to it. This is the one case a fallback ends the session.
+ * - **enter** — the user answered with anything else: another button, or free
+ *   text (no id at all). Free text the server cannot judge — "thanks, that's
+ *   it" is a meaning call that stays with the model — so it counts as staying.
+ * - **keep** — the ask timed out onto a non-exit fallback. Rule 5 recommends
+ *   `wait`/`review` there, and ask.ts returns the fallback id verbatim, so
+ *   reading it as an exit would drop a user out of REMOTE over an ask they
+ *   simply had not answered yet. Nor is it an entry: a timeout is not a user
+ *   action, and a NORMAL session must not become remote because nobody
+ *   replied. The mode is left exactly as it was.
+ */
+export type RemoteTransition = 'enter' | 'exit' | 'keep';
+export declare const remoteTransitionFor: (answer: {
+    actionId?: string;
+    timedOut: boolean;
+}) => RemoteTransition;
+/** `<stateDir>/remote-active-<projectHash>`, or null when the key can't be built. */
+export declare const remoteStatePath: () => string | null;
+/** Enter REMOTE, or push its expiry back. Best-effort: never throws. */
+export declare const enterRemote: () => void;
+/** Leave REMOTE. Best-effort: never throws, and a missing file is success. */
+export declare const exitRemote: () => void;
+//# sourceMappingURL=remote-state.d.ts.map

package/dist/remote-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-state.d.ts","sourceRoot":"","sources":["../src/remote-state.ts"],"names":[],"mappings":"AA8BA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,KAAG,OAC8B,CAAC;AAElF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzD,eAAO,MAAM,mBAAmB,GAC9B,QAAQ;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KAC/C,gBAGF,CAAC;AAKF,qFAAqF;AACrF,eAAO,MAAM,eAAe,QAAO,MAAM,GAAG,IAG3C,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,WAAW,QAAO,IAS9B,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,UAAU,QAAO,IAQ7B,CAAC"}

package/dist/remote-state.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exitRemote = exports.enterRemote = exports.remoteStatePath = exports.remoteTransitionFor = exports.isSessionExitId = void 0;
+/**
+ * Sticky REMOTE state — the server's half.
+ *
+ * REMOTE used to have nowhere to live: the model re-derived it every turn by
+ * rescanning the conversation. It now lives in a file, and this module is one
+ * of the two places that owns a transition. The other is the plugin's
+ * UserPromptSubmit hook, which enters REMOTE when a prompt matches a
+ * phone-injection marker; this module handles the transitions the server
+ * already knows about — a `zeph_ask` that came back answered.
+ *
+ * **Three implementations share the file format** — plugin/hooks/gate.sh
+ * (`zeph_remote_active` / `zeph_remote_touch`), cli/src/gate.ts
+ * (`isRemoteActive` / `touchRemoteActive`), and this file. Nothing checks them
+ * against each other at build time, so the format is pinned by literal
+ * assertions in remote-state.test.ts. The bash reader sweeps any non-numeric
+ * body on sight (`case "$ts" in *[!0-9]*)`), which means a JSON or ISO-8601
+ * body written here would enter REMOTE and be deleted by the very next prompt
+ * hook — silently, and invisibly from either repo's tests.
+ *
+ * There is no TTL logic here on purpose: expiry is the readers' job, and
+ * duplicating the window would give it two definitions.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const config_js_1 = require("./config.js");
+/** Action ids that end a remote session (CORE_RULES: case-insensitive). */
+const SESSION_EXIT_IDS = ['done', 'stop', 'exit'];
+/**
+ * True when this button ends the session. Case-insensitive by contract — the
+ * rules have always said so, but until now nothing enforced it, so a skill
+ * emitting `Done` would have read as a non-exit answer and left the user in
+ * REMOTE for the whole TTL.
+ */
+const isSessionExitId = (actionId) => SESSION_EXIT_IDS.includes(actionId.trim().toLowerCase());
+exports.isSessionExitId = isSessionExitId;
+const remoteTransitionFor = (answer) => {
+    if (answer.actionId !== undefined && (0, exports.isSessionExitId)(answer.actionId))
+        return 'exit';
+    return answer.timedOut ? 'keep' : 'enter';
+};
+exports.remoteTransitionFor = remoteTransitionFor;
+const stateDir = () => (0, path_1.join)(process.env.XDG_STATE_HOME || (0, path_1.join)((0, os_1.homedir)(), '.local', 'state'), 'zeph');
+/** `<stateDir>/remote-active-<projectHash>`, or null when the key can't be built. */
+const remoteStatePath = () => {
+    const hash = (0, config_js_1.projectHash)((0, config_js_1.detectProjectDir)());
+    return hash ? (0, path_1.join)(stateDir(), `remote-active-${hash}`) : null;
+};
+exports.remoteStatePath = remoteStatePath;
+/** Enter REMOTE, or push its expiry back. Best-effort: never throws. */
+const enterRemote = () => {
+    const file = (0, exports.remoteStatePath)();
+    if (!file)
+        return;
+    try {
+        (0, fs_1.mkdirSync)(stateDir(), { recursive: true });
+        (0, fs_1.writeFileSync)(file, `${Math.floor(Date.now() / 1000)}\n`);
+    }
+    catch {
+        /* an answered ask is still an answer — state IO must not reach the caller */
+    }
+};
+exports.enterRemote = enterRemote;
+/** Leave REMOTE. Best-effort: never throws, and a missing file is success. */
+const exitRemote = () => {
+    const file = (0, exports.remoteStatePath)();
+    if (!file)
+        return;
+    try {
+        (0, fs_1.unlinkSync)(file);
+    }
+    catch {
+        /* already gone, or unwritable — either way the caller has an answer */
+    }
+};
+exports.exitRemote = exitRemote;

package/dist/tools/ask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAwBxD,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SA+H7H,CAAC"}
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../../src/tools/ask.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAkDxD,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,QAAQ,aAAa,EAAE,QAAQ,eAAe,EAAE,SAAS,kBAAkB,SA+I7H,CAAC"}

package/dist/tools/ask.js

@@ -8,6 +8,7 @@ const config_js_1 = require("../config.js");
 const mime_js_1 = require("../mime.js");
 const sanitize_js_1 = require("../sanitize.js");
 const response_files_js_1 = require("../response-files.js");
+const remote_state_js_1 = require("../remote-state.js");
 // The device feed shows a short preview of the body. Anything longer than
 // this gets truncated there, so we attach the full text as a file — the
 // user can always open the complete content instead of squinting at a
@@ -21,9 +22,31 @@ const buildAskMarkdown = (title, body, actions) => {
     }
     return parts.join('\n');
 };
+/**
+ * Apply the mode transition this answer implies, and tell the model where it
+ * landed. The state itself lives in a file the prompt hooks also read, so the
+ * two carriers agree without either re-deriving REMOTE from the transcript.
+ *
+ * `zephState` is reported only when the server actually decided something. A
+ * timeout onto a safe fallback changes nothing, and naming a state there would
+ * mean re-reading the file — a fourth parser of a format three already share,
+ * to answer a question the server was not asked.
+ */
+const settleRemoteState = (answer) => {
+    switch ((0, remote_state_js_1.remoteTransitionFor)(answer)) {
+        case 'exit':
+            (0, remote_state_js_1.exitRemote)();
+            return { zephState: 'NORMAL' };
+        case 'enter':
+            (0, remote_state_js_1.enterRemote)();
+            return { zephState: 'REMOTE' };
+        case 'keep':
+            return {};
+    }
+};
 const registerAskTool = (server, client, config, waiter) => {
     server.registerTool('zeph_ask', {
-        description: 'Ask the user a question with optional quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
+        description: 'Ask the user a question with quick-reply buttons and a text input field. Combines prompt (buttons) and input (text) in a single notification. The user can either tap a button or type a response. `actions` is the steering surface, not decoration: pass 2–4 buttons on nearly every ask — the next-step candidates you would otherwise write as prose (next command, review, stop) plus a safe Done-like `fallback`. Leave `actions` out ONLY when the answer is inherently free-form text (a name, a path, a paragraph); a bare text box on a "done — what next?" ask leaves the phone with nothing to tap. Blocks until the user responds or the timeout is reached. Requires ZEPH_HOOK_ID environment variable. The user may also attach screenshots or files to the answer: those arrive as local absolute paths in the `attachments` field of the result, and reading them is part of reading the answer. NOTE: unlike zeph_notify and zeph_file, this tool is never end-to-end encrypted — the hook route it uses cannot carry the sender key — so do not put secrets in the question or expect a private answer.',
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -42,7 +65,7 @@ const registerAskTool = (server, client, config, waiter) => {
                 .min(1)
                 .max(4)
                 .optional()
-                .describe('Quick-reply buttons (1-4). Omit for text-only input'),
+                .describe('Quick-reply buttons (1-4). Expected on nearly every ask — the phone steers by tapping, so put the next-step candidates here (next command, review, stop) plus a Done-like fallback. Omit ONLY when the answer is inherently free-form text; never omit on a "done — what next?" ask.'),
             placeholder: zod_1.z.string().optional().describe('Input field placeholder hint'),
             inputType: zod_1.z
                 .enum(['text', 'multiline'])
@@ -108,8 +131,13 @@ const registerAskTool = (server, client, config, waiter) => {
             });
             const event = await (0, poll_js_1.pollForResponse)(client, config.hookId, trigger.data.eventId, timeout, ctx, waiter);
             if (!event) {
-                if (fallback)
-                    return (0, error_format_js_1.textResult)({ actionId: fallback, timedOut: true });
+                if (fallback) {
+                    return (0, error_format_js_1.textResult)({
+                        actionId: fallback,
+                        timedOut: true,
+                        ...settleRemoteState({ actionId: fallback, timedOut: true }),
+                    });
+                }
                 return (0, error_format_js_1.timeoutError)(timeout, 'Try again or use zeph_notify for one-way communication');
             }
             const response = event.data.response;
@@ -118,9 +146,19 @@ const registerAskTool = (server, client, config, waiter) => {
             // silently for the one caller that never looks at `value`.
             const attachments = await (0, response_files_js_1.saveResponseFiles)(client, trigger.data.eventId, response?.files);
             if (response?.actionId) {
-                return (0, error_format_js_1.textResult)({ actionId: response.actionId, timedOut: false, ...(0, response_files_js_1.attachmentNote)(attachments) });
+                return (0, error_format_js_1.textResult)({
+                    actionId: response.actionId,
+                    timedOut: false,
+                    ...settleRemoteState({ actionId: response.actionId, timedOut: false }),
+                    ...(0, response_files_js_1.attachmentNote)(attachments),
+                });
             }
-            return (0, error_format_js_1.textResult)({ value: response?.value ?? '', timedOut: false, ...(0, response_files_js_1.attachmentNote)(attachments) });
+            return (0, error_format_js_1.textResult)({
+                value: response?.value ?? '',
+                timedOut: false,
+                ...settleRemoteState({ timedOut: false }),
+                ...(0, response_files_js_1.attachmentNote)(attachments),
+            });
         }
         catch (err) {
             return (0, error_format_js_1.formatToolError)(err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/mcp-server",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Zeph MCP server — AI agent notifications, prompts, and input via MCP protocol",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",