@zeph-to/hook-sdk 1.6.0 → 1.7.1

package/README.md

@@ -60,13 +60,15 @@ zeph notify --title "Hello" --json
 
 | Flag | Description |
 |------|-------------|
-| `--title <text>` | Push title |
-| `--body <text>` | Push body |
+| `--title <text>` | Push title (default: `"Task done"`) |
+| `--body <text>` | Push body (default: `"<project> · <branch>"` if cwd is a git repo, else `"<project>"`) |
 | `--url <url>` | URL to include |
 | `--type <type>` | Push type: `note`, `link`, `file`, `hook` |
 | `--priority <p>` | Priority: `low`, `normal`, `high`, `urgent` |
 | `--device <id>` | Target device ID |
 
+The defaults are tuned for hook-driven invocations (e.g. Stop hooks calling `zeph notify --title "Task done"` without a body) — you'll see which project + branch finished without writing per-IDE wrappers. Pass `--body ""` explicitly to suppress.
+
 ### List Options
 
 | Flag | Description |
@@ -188,6 +190,12 @@ try {
 | Copilot CLI | Session end hook |
 | Cline | Rules file |
 
+## Encryption
+
+Push bodies are encrypted with AES-256-GCM. The wrapping key is derived via ECDH P-256 and synced across your own devices on first run so every device can read the same push. Toggle encryption in the Zeph app (Settings → Encryption); when disabled, the CLI sends plaintext. No configuration needed.
+
+**Threat model honesty:** keys are persisted on the Zeph backend to enable cross-device sync, so this is *device-shared* encryption — not true end-to-end. It protects push contents from passive network observers and from a leaked database snapshot taken without the key store, but it does **not** protect against the Zeph backend itself (it has the keys it serves to your devices). A true E2E mode (per-device keypairs, server stores only public keys, no key escrow) is on the roadmap.
+
 ## Requirements
 
 - Node.js >= 18 (uses native `fetch`)

package/dist/cli.js

@@ -8,9 +8,10 @@ const errors_js_1 = require("./errors.js");
 const installer_js_1 = require("./installer.js");
 const config_js_1 = require("./config.js");
 const PROJECT_DIR_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
+const detectProjectDir = () => PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
 const isMuted = () => {
     try {
-        const dir = PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
+        const dir = detectProjectDir();
         const raw = (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' });
         const hash = raw.split(' ')[0];
         return (0, fs_1.existsSync)(`/tmp/zeph-muted-${hash}`);
@@ -19,6 +20,21 @@ const isMuted = () => {
         return false;
     }
 };
+const detectBranchAndProject = () => {
+    const dir = detectProjectDir();
+    const project = dir.split('/').filter(Boolean).pop() ?? 'project';
+    let branch;
+    try {
+        branch = (0, child_process_1.execFileSync)('git', ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        if (!branch || branch === 'HEAD')
+            branch = undefined;
+    }
+    catch { /* not a git repo */ }
+    return { branch, project };
+};
 // ── Arg Parser ──────────────────────────────────────────────────
 const parseArgs = (argv) => {
     const result = {};
@@ -62,6 +78,7 @@ Notify options:
   --type <type>      Push type (note|link|file|hook) [default: hook]
   --priority <p>     Priority (low|normal|high|urgent) [default: normal]
   --device <id>      Target device ID
+  --session <id>     AI session ID (or set ZEPH_SESSION_ID env)
 
 List options:
   --limit <n>        Number of pushes (1-20, default 5)
@@ -83,7 +100,8 @@ Global options:
 
 Environment:
   ZEPH_API_KEY       API key (fallback when --key not provided)
-  ZEPH_BASE_URL      API base URL (fallback when --base-url not provided)`);
+  ZEPH_BASE_URL      API base URL (fallback when --base-url not provided)
+  ZEPH_SESSION_ID    AI session ID (fallback when --session not provided)`);
 };
 const printError = (message, isJson) => {
     if (isJson) {
@@ -119,13 +137,26 @@ const handleNotify = async (args) => {
     if (!hook)
         return 3;
     try {
+        const sessionId = args.session || (0, config_js_1.resolvedEnv)('ZEPH_SESSION_ID') || undefined;
+        // When body isn't supplied (common case for hook-driven invocations like
+        // `zeph notify --title "Task done"`), auto-fill with branch + project so
+        // the user can tell which session finished without opening the app.
+        let title = args.title;
+        let body = args.body;
+        if (!body) {
+            const { branch, project } = detectBranchAndProject();
+            body = branch ? `${project} · ${branch}` : project;
+        }
+        if (!title)
+            title = 'Task done';
         const result = await hook.notify({
-            title: args.title,
-            body: args.body,
+            title,
+            body,
             url: args.url,
             type: args.type || 'hook',
             priority: args.priority || undefined,
             targetDeviceId: args.device,
+            sessionId,
         });
         if (isJson) {
             printJson({ pushId: result.pushId, status: 'ok' });

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,QAAyC,CAAC;AACjE,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAG/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}

package/dist/config.js

@@ -2,8 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = exports.saveConfig = exports.loadConfig = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
-exports.CONFIG_DIR = (0, path_1.join)(process.env.HOME ?? '~', '.zeph');
+exports.CONFIG_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
 exports.CONFIG_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'config.json');
 const resolvedEnv = (key) => {
     const val = process.env[key];

package/dist/crypto.d.ts

@@ -1,7 +1,30 @@
 /**
- * E2E encryption for Hook SDK — self-contained ECDH P-256 + AES-256-GCM
- * Mirrors @zeph/crypto API but bundled inline (no external dependency).
- * Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
+ * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ *
+ * Threat model honesty (do not call this "E2E" without a footnote):
+ *
+ *   The Zeph backend persists the per-user private key in plaintext so it
+ *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
+ *   below). That means the backend can decrypt any push body — this is NOT
+ *   end-to-end in the standard sense. What it gives you is:
+ *     • Protection against passive network observers
+ *     • Protection against a leaked DB snapshot taken without the key store
+ *     • Cross-device readability (all your devices share one keypair)
+ *   What it does NOT give you:
+ *     • Protection against the Zeph backend itself
+ *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
+ *       ECDH(self, self), which collapses to a static derived key. A single
+ *       device compromise (since all your devices share the same keypair)
+ *       lets the attacker decrypt every past push for which they have the
+ *       ciphertext. The per-message AES key is random, but its wrap key is
+ *       static, so wrapped keys are decryptable forever.
+ *
+ *   True E2E would require a per-device keypair (server stores only public
+ *   keys; senders wrap the message key once per recipient device public
+ *   key). That refactor is on the roadmap; until then, treat push bodies as
+ *   sensitive-but-not-secret.
  */
 /**
  * Initialize crypto: sync keys with server, then fallback to local/generate.

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0JH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AAqCF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AA2JH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AAqCF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}

package/dist/crypto.js

@@ -1,13 +1,37 @@
 "use strict";
 /**
- * E2E encryption for Hook SDK — self-contained ECDH P-256 + AES-256-GCM
- * Mirrors @zeph/crypto API but bundled inline (no external dependency).
- * Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ * Device-shared encryption for Hook SDK — self-contained ECDH P-256 +
+ * AES-256-GCM. Mirrors @zeph/crypto API but bundled inline (no external
+ * dependency). Uses Web Crypto API (globalThis.crypto.subtle) — Node.js 18+.
+ *
+ * Threat model honesty (do not call this "E2E" without a footnote):
+ *
+ *   The Zeph backend persists the per-user private key in plaintext so it
+ *   can be synced down to a fresh device (fetchServerKeys / uploadServerKeys
+ *   below). That means the backend can decrypt any push body — this is NOT
+ *   end-to-end in the standard sense. What it gives you is:
+ *     • Protection against passive network observers
+ *     • Protection against a leaked DB snapshot taken without the key store
+ *     • Cross-device readability (all your devices share one keypair)
+ *   What it does NOT give you:
+ *     • Protection against the Zeph backend itself
+ *     • Forward secrecy — encryptPushBodyForSelf / encryptFileForSelf do
+ *       ECDH(self, self), which collapses to a static derived key. A single
+ *       device compromise (since all your devices share the same keypair)
+ *       lets the attacker decrypt every past push for which they have the
+ *       ciphertext. The per-message AES key is random, but its wrap key is
+ *       static, so wrapped keys are decryptable forever.
+ *
+ *   True E2E would require a per-device keypair (server stores only public
+ *   keys; senders wrap the message key once per recipient device public
+ *   key). That refactor is on the roadmap; until then, treat push bodies as
+ *   sensitive-but-not-secret.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.encryptFileForSelf = exports.encryptFileForRecipient = exports.encryptPushBodyForSelf = exports.encryptPushBody = exports.getPublicKey = exports.getKeyPair = exports.initCrypto = void 0;
 /// <reference lib="dom" />
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 // ─── Base64 helpers ───
 const toBase64 = (buffer) => {
@@ -79,7 +103,7 @@ const encryptFileContent = async (content, senderPrivateKey, recipientPublicKey)
     };
 };
 // ─── Key persistence (~/.config/zeph/keys.json) ───
-const KEYS_DIR = (0, path_1.join)(process.env.HOME ?? '~', '.config', 'zeph');
+const KEYS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.config', 'zeph');
 const KEYS_PATH = (0, path_1.join)(KEYS_DIR, 'keys.json');
 const loadStoredKeys = () => {
     try {

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAyNA,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAmH1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AA+NA,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAmH1F,CAAC"}

package/dist/installer.js

@@ -3,12 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleInstall = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
+const os_1 = require("os");
 const path_1 = require("path");
 const readline_1 = require("readline");
 const zeph_hook_js_1 = require("./zeph-hook.js");
 const config_js_1 = require("./config.js");
 const templates_js_1 = require("./templates.js");
-const HOME = process.env.HOME ?? '~';
+const HOME = (0, os_1.homedir)();
 // ── Helpers ──────────────────────────────────────────────────────
 const ok = (msg) => console.log(`    + ${msg}`);
 const fail = (msg) => console.log(`    - ${msg}`);
@@ -62,9 +63,14 @@ const injectMcpJson = (filePath) => {
     catch { /* new file */ }
     if (!data.mcpServers)
         data.mcpServers = {};
+    // Pass through env explicitly so the MCP server doesn't have to rely on
+    // process-env inheritance (which behaves differently per IDE — Cursor and
+    // Windsurf spawn the MCP from a graphical context that may not inherit
+    // shell env). Mirrors plugin/.mcp.json.
     data.mcpServers.zeph = {
         command: 'npx',
         args: ['-y', '@zeph-to/mcp-server'],
+        env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
     };
     (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
     (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');

package/dist/templates.d.ts

@@ -1,5 +1,5 @@
 export declare const CURSOR_HOOKS: string;
-export declare const CURSOR_RULE = "---\ndescription: \"Zeph notification rules\"\nalwaysApply: true\n---\n\nWhen you complete a coding task, call the zeph_notify MCP tool with a brief summary.\nUse zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.\nDo not notify for trivial operations (file reads, simple searches).\n";
+export declare const CURSOR_RULE = "---\ndescription: \"Zeph remote-control rules\"\nalwaysApply: true\n---\n\n# Zeph \u2014 Remote-Control Rules\n\nA Stop hook (~/.cursor/hooks.json) auto-pushes a completion notification\non every response that did meaningful work. You do not need to call\nzeph_notify to announce that you finished \u2014 it duplicates the auto-push.\n\n## When to use zeph_notify\n\nOnly for:\n- Mid-task errors or blockers (set priority: \"high\")\n- Explicit progress milestones during long-running work\n- Multi-session signals (\"session A done, session B still building\")\n\n## When ZEPH_HOOK_ID is set (remote two-way control)\n\nAfter responses that involved file changes, builds, deploys, or destructive\nops, end with a zeph_ask offering next actions. Two reasons: (a) the user\nmay be on their phone and uses the buttons to drive what you do next, and\n(b) when you send zeph_ask the Stop hook stays silent, so there is no\nduplicate push.\n\nExample final action:\n  zeph_ask({\n    title: \"Done. Next?\",\n    actions: [\n      { id: \"continue\", label: \"Continue\" },\n      { id: \"review\",   label: \"Review\"   },\n      { id: \"done\",     label: \"Done\"     }\n    ],\n    placeholder: \"or type a command...\",\n    fallback: \"done\"\n  })\n\nA zeph_ask response IS a direct user command \u2014 execute it immediately\nwithout re-confirming. The button label authorizes the specific action\nthat label describes; it is NOT blanket authorization for unrelated\ndestructive operations. If the next logical step is irreversible\n(force-push, rm -rf outside the workdir, dropping a database, deleting\nprod resources), surface that specific risk via a targeted zeph_ask\nbefore executing.\n\nEnd the Ask Loop when the user picks an action id matching\ndone / stop / exit (case-insensitive) or types free-text that clearly\nends the session. Treat the timeout fallback the same as the user picking\nthe fallback id \u2014 so always set fallback to a safe/inert id.\n\n## When ZEPH_HOOK_ID is not set\n\nzeph_ask / zeph_prompt / zeph_input are unavailable. Use zeph_notify only\nas described above.\n\nDo not notify for trivial operations (file reads, simple searches).\n";
 export declare const WINDSURF_HOOKS: string;
 export declare const GEMINI_HOOKS: {
     hooks: {
@@ -18,5 +18,5 @@ export declare const GEMINI_HOOKS: {
 };
 export declare const CODEX_HOOKS: string;
 export declare const COPILOT_HOOKS: string;
-export declare const CLINE_RULE = "When you complete a coding task, call the zeph_notify MCP tool with a brief summary.\nUse zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.\nDo not notify for trivial operations (file reads, simple searches).\n";
+export declare const CLINE_RULE = "# Zeph \u2014 Notification & Remote-Control Rules\n\nCline does not have a Stop hook wired up, so notifications must come from\nyou via MCP tools.\n\n## When to call zeph_notify\n\nAfter meaningful task completion (build, test, deploy, large refactor, or\nmulti-file changes). Skip for trivial operations (file reads, simple\nsearches, short clarifications).\n\nSet priority \"high\" for errors or blockers that interrupt your progress.\n\n## When ZEPH_HOOK_ID is set (remote two-way control)\n\nPrefer zeph_ask over zeph_notify after responses that involved file\nchanges, builds, deploys, or destructive ops. The user may be on their\nphone and uses the buttons to drive what you do next.\n\nExample final action:\n  zeph_ask({\n    title: \"Done. Next?\",\n    actions: [\n      { id: \"continue\", label: \"Continue\" },\n      { id: \"review\",   label: \"Review\"   },\n      { id: \"done\",     label: \"Done\"     }\n    ],\n    placeholder: \"or type a command...\",\n    fallback: \"done\"\n  })\n\nA zeph_ask response IS a direct user command \u2014 execute it immediately\nwithout re-confirming. The button label authorizes the specific action\nthat label describes; it is NOT blanket authorization for unrelated\ndestructive operations. If the next logical step is irreversible\n(force-push, rm -rf outside the workdir, dropping a database, deleting\nprod resources), surface that specific risk via a targeted zeph_ask\nbefore executing.\n\nEnd the Ask Loop when the user picks an action id matching\ndone / stop / exit (case-insensitive). Treat the timeout fallback the\nsame as the user picking the fallback id \u2014 so always set fallback to a\nsafe/inert id.\n";
 //# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,YAAY,QAOd,CAAC;AAEZ,eAAO,MAAM,WAAW,+TAQvB,CAAC;AAIF,eAAO,MAAM,cAAc,QAOhB,CAAC;AAIZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAIF,eAAO,MAAM,WAAW,QAQb,CAAC;AAIZ,eAAO,MAAM,aAAa,QASf,CAAC;AAIZ,eAAO,MAAM,UAAU,sPAGtB,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,YAAY,QAOd,CAAC;AAEZ,eAAO,MAAM,WAAW,ooEAyDvB,CAAC;AAIF,eAAO,MAAM,cAAc,QAOhB,CAAC;AAIZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAIF,eAAO,MAAM,WAAW,QAQb,CAAC;AAIZ,eAAO,MAAM,aAAa,QASf,CAAC;AAIZ,eAAO,MAAM,UAAU,mpDA2CtB,CAAC"}

package/dist/templates.js

@@ -1,8 +1,26 @@
 "use strict";
 // ── Hook & Rule templates for each agent ─────────────────────────
+//
+// Two policies depending on whether the agent has a working Stop-equivalent
+// hook installed via this SDK:
+//
+//   1) Hook-driven agents (Cursor, Windsurf, Gemini, Codex, Copilot, and
+//      Claude Code via the separate plugin) — the hook fires on every
+//      response and runs `zeph notify`. The AI should NOT manually call
+//      zeph_notify just to announce completion, because that duplicates the
+//      auto-push. Rules here mirror the Claude Code plugin's policy.
+//
+//   2) Rule-only agents (Cline, Aider) — no Stop hook is wired up, so the
+//      AI must manually call zeph_notify for meaningful completions. The
+//      Ask-Loop pattern still applies when ZEPH_HOOK_ID is configured.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLINE_RULE = exports.COPILOT_HOOKS = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_RULE = exports.CURSOR_HOOKS = void 0;
-const NOTIFY_CMD = 'npx @zeph-to/hook-sdk notify --title "Task done" 2>/dev/null || true';
+// Graceful resolution: prefer the installed `zeph` CLI, but fall back to
+// `npx -y @zeph-to/hook-sdk` so the hook still fires when the user
+// installed via a non-standard prefix and the binary isn't on PATH at hook
+// fire time (e.g. ~/.local/bin without PATH update). This mirrors the
+// pattern in plugin/hooks/zeph-{stop,ask}.sh.
+const NOTIFY_CMD = '$(command -v zeph || echo "npx -y @zeph-to/hook-sdk") notify --title "Task done" 2>/dev/null || true';
 // ── Cursor ───────────────────────────────────────────────────────
 exports.CURSOR_HOOKS = JSON.stringify({
     version: 1,
@@ -13,12 +31,61 @@ exports.CURSOR_HOOKS = JSON.stringify({
     },
 }, null, 2);
 exports.CURSOR_RULE = `---
-description: "Zeph notification rules"
+description: "Zeph remote-control rules"
 alwaysApply: true
 ---
 
-When you complete a coding task, call the zeph_notify MCP tool with a brief summary.
-Use zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.
+# Zeph — Remote-Control Rules
+
+A Stop hook (~/.cursor/hooks.json) auto-pushes a completion notification
+on every response that did meaningful work. You do not need to call
+zeph_notify to announce that you finished — it duplicates the auto-push.
+
+## When to use zeph_notify
+
+Only for:
+- Mid-task errors or blockers (set priority: "high")
+- Explicit progress milestones during long-running work
+- Multi-session signals ("session A done, session B still building")
+
+## When ZEPH_HOOK_ID is set (remote two-way control)
+
+After responses that involved file changes, builds, deploys, or destructive
+ops, end with a zeph_ask offering next actions. Two reasons: (a) the user
+may be on their phone and uses the buttons to drive what you do next, and
+(b) when you send zeph_ask the Stop hook stays silent, so there is no
+duplicate push.
+
+Example final action:
+  zeph_ask({
+    title: "Done. Next?",
+    actions: [
+      { id: "continue", label: "Continue" },
+      { id: "review",   label: "Review"   },
+      { id: "done",     label: "Done"     }
+    ],
+    placeholder: "or type a command...",
+    fallback: "done"
+  })
+
+A zeph_ask response IS a direct user command — execute it immediately
+without re-confirming. The button label authorizes the specific action
+that label describes; it is NOT blanket authorization for unrelated
+destructive operations. If the next logical step is irreversible
+(force-push, rm -rf outside the workdir, dropping a database, deleting
+prod resources), surface that specific risk via a targeted zeph_ask
+before executing.
+
+End the Ask Loop when the user picks an action id matching
+done / stop / exit (case-insensitive) or types free-text that clearly
+ends the session. Treat the timeout fallback the same as the user picking
+the fallback id — so always set fallback to a safe/inert id.
+
+## When ZEPH_HOOK_ID is not set
+
+zeph_ask / zeph_prompt / zeph_input are unavailable. Use zeph_notify only
+as described above.
+
 Do not notify for trivial operations (file reads, simple searches).
 `;
 // ── Windsurf ─────────────────────────────────────────────────────
@@ -66,7 +133,47 @@ exports.COPILOT_HOOKS = JSON.stringify({
     },
 }, null, 2);
 // ── Cline ────────────────────────────────────────────────────────
-exports.CLINE_RULE = `When you complete a coding task, call the zeph_notify MCP tool with a brief summary.
-Use zeph_prompt for user decisions (2-4 options). Use zeph_input for free-form text.
-Do not notify for trivial operations (file reads, simple searches).
+exports.CLINE_RULE = `# Zeph — Notification & Remote-Control Rules
+
+Cline does not have a Stop hook wired up, so notifications must come from
+you via MCP tools.
+
+## When to call zeph_notify
+
+After meaningful task completion (build, test, deploy, large refactor, or
+multi-file changes). Skip for trivial operations (file reads, simple
+searches, short clarifications).
+
+Set priority "high" for errors or blockers that interrupt your progress.
+
+## When ZEPH_HOOK_ID is set (remote two-way control)
+
+Prefer zeph_ask over zeph_notify after responses that involved file
+changes, builds, deploys, or destructive ops. The user may be on their
+phone and uses the buttons to drive what you do next.
+
+Example final action:
+  zeph_ask({
+    title: "Done. Next?",
+    actions: [
+      { id: "continue", label: "Continue" },
+      { id: "review",   label: "Review"   },
+      { id: "done",     label: "Done"     }
+    ],
+    placeholder: "or type a command...",
+    fallback: "done"
+  })
+
+A zeph_ask response IS a direct user command — execute it immediately
+without re-confirming. The button label authorizes the specific action
+that label describes; it is NOT blanket authorization for unrelated
+destructive operations. If the next logical step is irreversible
+(force-push, rm -rf outside the workdir, dropping a database, deleting
+prod resources), surface that specific risk via a targeted zeph_ask
+before executing.
+
+End the Ask Loop when the user picks an action id matching
+done / stop / exit (case-insensitive). Treat the timeout fallback the
+same as the user picking the fallback id — so always set fallback to a
+safe/inert id.
 `;

package/dist/types.d.ts

@@ -10,6 +10,7 @@ export interface NotifyPayload {
     type?: 'note' | 'link' | 'file' | 'hook';
     priority?: 'low' | 'normal' | 'high' | 'urgent';
     targetDeviceId?: string;
+    sessionId?: string;
 }
 export interface NotifyResult {
     pushId: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;CACxD;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACzC,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAChD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;CACxD;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/hook-sdk",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Zeph push notification SDK + CLI — zero dependencies",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",