@zeph-to/cli 1.18.0 → 1.19.0

package/README.md

@@ -106,6 +106,25 @@ The listener also reports its tmux session inventory back to the server
 every 5 seconds, so the phone picker stays in sync — no manual
 configuration needed once a session is running.
 
+### Remote-origin detection (sticky REMOTE mode)
+
+A message injected via `send-keys` is indistinguishable from typing — so
+the listener also records each injection as a one-shot marker (epoch +
+sha256 of the text, keyed by the pane's project dir). A prompt-submit
+hook on the agent side matches the submitted prompt against that marker
+and, on an exact match, tells the model the user is driving the session
+from their phone — entering sticky REMOTE mode (every response ends with
+an answerable `zeph_ask`).
+
+| Agent | Hook | Installed by |
+|-------|------|--------------|
+| Claude Code | `UserPromptSubmit` → plugin's `zeph-remote.sh` | Zeph plugin |
+| Gemini CLI | `BeforeAgent` → `zeph remote-hook gemini` | `zeph setup` |
+| Codex CLI | `UserPromptSubmit` → `zeph remote-hook codex` | `zeph setup` |
+
+Detection is exact-match: a terminal keystroke racing a phone message
+can never false-flag. Muted projects are never flagged.
+
 ### Setup
 
 1. **Install tmux.** The listener uses `send-keys`; the wrapper spawns

package/dist/cli.js

@@ -14,6 +14,7 @@ const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
 const gate_js_1 = require("./gate.js");
 const remote_agents_js_1 = require("./remote-agents.js");
+const remote_hook_js_1 = require("./remote-hook.js");
 const detectBranchAndProject = () => {
     const dir = (0, config_js_1.detectProjectDir)();
     const project = dir.split('/').filter(Boolean).pop() ?? 'project';
@@ -164,6 +165,30 @@ const gateCount = (raw, fallback) => {
     const n = typeof raw === 'string' ? Number(raw) : NaN;
     return Number.isFinite(n) && n >= 0 ? n : fallback;
 };
+/**
+ * Internal — invoked by the Gemini/Codex prompt-submit hooks that
+ * `zeph setup` registers, never typed by users (hence absent from help).
+ * Reads the hook JSON on stdin; prints additionalContext JSON on a match
+ * (remote-origin detection, ADR-0002). Always exits 0: the hook only adds
+ * context and must never block a prompt.
+ */
+const handleRemoteHook = async (args) => {
+    const agent = args._arg1;
+    if (!(0, remote_hook_js_1.isRemoteHookAgent)(agent))
+        return 0;
+    try {
+        let stdin = '';
+        for await (const chunk of process.stdin)
+            stdin += chunk;
+        const out = (0, remote_hook_js_1.runRemoteHook)(agent, stdin);
+        if (out)
+            console.log(out);
+    }
+    catch {
+        /* never block a prompt */
+    }
+    return 0;
+};
 const handleNotify = async (args) => {
     const isJson = args.json === true;
     const projectDir = (0, config_js_1.detectProjectDir)();
@@ -384,6 +409,8 @@ const main = async () => {
             return handleTest(args);
         case 'listener':
             return (0, listener_js_1.handleListener)(args);
+        case 'remote-hook':
+            return handleRemoteHook(args);
         default:
             printError(`Unknown command: ${command}`, args.json === true);
             printUsage();

package/dist/gate.d.ts

@@ -30,6 +30,15 @@ export declare const normalizePushMode: (raw: string | undefined) => GatePushMod
 export declare const decidePush: (input: GateInput) => GateVerdict;
 export declare const stateDir: () => string;
 export declare const projectHash: (dir: string) => string | null;
+/** Marker path for a project hash: `<stateDir>/remote-<cksum(projectDir)>`. */
+export declare const remoteMarkerPath: (hash: string) => string;
+/**
+ * sha256 over the ASCII-only-trimmed text — recorded at inject time,
+ * recomputed at prompt submit. Trim strips ONLY ' \t\r\n\f\v', NOT
+ * String.trim(): trim() also eats Unicode whitespace (U+00A0 etc.) that
+ * the bash reader keeps, and both sides must hash identical bytes.
+ */
+export declare const remoteDigest: (text: string) => string;
 /** True when the user ran /zeph-mute for this project. */
 export declare const isMuted: (dir: string) => boolean;
 /** The user's session push-mode dial (/zeph-quiet | /zeph-loud), default normal. */

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AAmBjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAEF,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,YAU1C,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AAmBjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAWF,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAG1B,CAAC;AAEnB,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,YAU1C,CAAC"}

package/dist/gate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readPushMode = exports.isMuted = exports.projectHash = exports.stateDir = exports.decidePush = exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = void 0;
+exports.readPushMode = exports.isMuted = exports.remoteDigest = exports.remoteMarkerPath = exports.projectHash = exports.stateDir = exports.decidePush = exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = void 0;
 /**
  * Push-gate decision — the portable half of the Zeph Stop-hook logic.
  *
@@ -21,6 +21,7 @@ exports.readPushMode = exports.isMuted = exports.projectHash = exports.stateDir
  *      (the B1 read-only floor).
  */
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -95,6 +96,27 @@ const projectHash = (dir) => {
     }
 };
 exports.projectHash = projectHash;
+// ── Remote-origin marker (ADR-0002) ──────────────────────────────
+//
+// The listener records every phone→pane text injection as a one-shot
+// marker file; a prompt-submit hook (Claude Code plugin's zeph-remote.sh,
+// or `zeph remote-hook` for Gemini/Codex) consumes it on an exact-text
+// match and flags the prompt as remote-originated. Writer and TS reader
+// share these two helpers so their bytes can never diverge; the bash
+// reader is held to the same semantics by the plugin's test suite.
+/** Marker path for a project hash: `<stateDir>/remote-<cksum(projectDir)>`. */
+const remoteMarkerPath = (hash) => (0, path_1.join)((0, exports.stateDir)(), `remote-${hash}`);
+exports.remoteMarkerPath = remoteMarkerPath;
+/**
+ * sha256 over the ASCII-only-trimmed text — recorded at inject time,
+ * recomputed at prompt submit. Trim strips ONLY ' \t\r\n\f\v', NOT
+ * String.trim(): trim() also eats Unicode whitespace (U+00A0 etc.) that
+ * the bash reader keeps, and both sides must hash identical bytes.
+ */
+const remoteDigest = (text) => (0, crypto_1.createHash)('sha256')
+    .update(text.replace(/^[ \t\r\n\f\v]+|[ \t\r\n\f\v]+$/g, ''))
+    .digest('hex');
+exports.remoteDigest = remoteDigest;
 /** True when the user ran /zeph-mute for this project. */
 const isMuted = (dir) => {
     const hash = (0, exports.projectHash)(dir);

package/dist/installer.d.ts

@@ -4,6 +4,9 @@ import type { Agent } from './agents.js';
  * context with no existing credential (--key/env/config all absent).
  */
 export declare const shouldTriggerLogin: (nonInteractive: boolean, currentKey: string | undefined) => boolean;
+/** Exported for tests (installGemini shells out to the real `gemini` binary,
+ *  so the merge semantics can't be covered through it deterministically). */
+export declare const mergeJsonFile: (filePath: string, patch: Record<string, unknown>) => void;
 /**
  * Resolve agents from a non-interactive `--only cursor,gemini` flag.
  * Matches on agent id; unknown ids are silently dropped. Exported for

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA2BzC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,OAAO,EAAE,YAAY,MAAM,GAAG,SAAS,KAAG,OAC7D,CAAC;AA+QjC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA4FF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAkG1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA4BzC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,OAAO,EAAE,YAAY,MAAM,GAAG,SAAS,KAAG,OAC7D,CAAC;AAoBjC;6EAC6E;AAC7E,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAqBhF,CAAC;AAuPF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA4FF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAkG1F,CAAC"}

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = exports.filterAgentsByIds = exports.shouldTriggerLogin = void 0;
+exports.handleInstall = exports.filterAgentsByIds = exports.mergeJsonFile = exports.shouldTriggerLogin = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -34,6 +34,9 @@ const writeFile = (filePath, content) => {
     (0, fs_1.mkdirSync)((0, path_1.dirname)(filePath), { recursive: true });
     (0, fs_1.writeFileSync)(filePath, content + '\n');
 };
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Exported for tests (installGemini shells out to the real `gemini` binary,
+ *  so the merge semantics can't be covered through it deterministically). */
 const mergeJsonFile = (filePath, patch) => {
     let data = {};
     try {
@@ -41,8 +44,23 @@ const mergeJsonFile = (filePath, patch) => {
     }
     catch { /* new file */ }
     const merged = { ...data, ...patch };
+    // `hooks` maps event names to matcher-group arrays, and the user may own
+    // entries at BOTH levels (their own events, and their own groups inside
+    // an event zeph also uses) — so instead of clobbering the whole object,
+    // merge events, and inside each event zeph writes keep the user's groups
+    // and replace only zeph's own (re-runs stay idempotent).
+    if (isPlainObject(data.hooks) && isPlainObject(patch.hooks)) {
+        const hooks = { ...data.hooks };
+        for (const [event, patchGroups] of Object.entries(patch.hooks)) {
+            const prev = hooks[event];
+            const userGroups = Array.isArray(prev) ? prev.filter((g) => !(0, templates_js_1.isZephHookGroup)(g)) : [];
+            hooks[event] = [...userGroups, ...(Array.isArray(patchGroups) ? patchGroups : [])];
+        }
+        merged.hooks = hooks;
+    }
     writeFile(filePath, JSON.stringify(merged, null, 2));
 };
+exports.mergeJsonFile = mergeJsonFile;
 /**
  * Write a Zeph rule into a SHARED agent rule file (Windsurf global_rules.md,
  * Gemini GEMINI.md, Codex AGENTS.md) without clobbering the user's own
@@ -168,8 +186,8 @@ const installGemini = () => {
         fail('MCP add failed. Manual: gemini mcp add zeph -- npx -y @zeph-to/mcp-server');
     }
     try {
-        mergeJsonFile((0, path_1.join)(HOME, '.gemini', 'settings.json'), templates_js_1.GEMINI_HOOKS);
-        ok('AfterAgent hook added');
+        (0, exports.mergeJsonFile)((0, path_1.join)(HOME, '.gemini', 'settings.json'), templates_js_1.GEMINI_HOOKS);
+        ok('BeforeAgent + AfterAgent hooks added');
     }
     catch {
         fail('Hook install failed');
@@ -185,8 +203,8 @@ const installGemini = () => {
 };
 const installCodex = () => {
     try {
-        writeFile((0, path_1.join)(HOME, '.codex', 'hooks.json'), templates_js_1.CODEX_HOOKS);
-        ok('Stop hook added');
+        (0, exports.mergeJsonFile)((0, path_1.join)(HOME, '.codex', 'hooks.json'), templates_js_1.CODEX_HOOKS);
+        ok('UserPromptSubmit + Stop hooks added');
     }
     catch {
         fail('Hook install failed. Manual: add zeph to ~/.codex/hooks.json');

package/dist/listener.d.ts

@@ -211,9 +211,10 @@ interface HandlePushDeps {
     paneCwd?: (session: string) => string | null;
 }
 /**
- * Record a successful phone→pane text injection so the plugin's
- * UserPromptSubmit hook can flag the matching prompt as remote-originated
- * and enter sticky REMOTE mode (ADR-0002). One file per project dir,
+ * Record a successful phone→pane text injection so a prompt-submit hook
+ * (Claude Code plugin's zeph-remote.sh, or `zeph remote-hook` for
+ * Gemini/Codex) can flag the matching prompt as remote-originated and
+ * enter sticky REMOTE mode (ADR-0002). One file per project dir,
  * overwritten on every inject; the hook consumes it on an exact-text match.
  * Best-effort: a write failure must never fail the injection itself.
  */

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}

package/dist/listener.js

@@ -774,9 +774,10 @@ const passesInjectGuards = (session, deps) => {
     return true;
 };
 /**
- * Record a successful phone→pane text injection so the plugin's
- * UserPromptSubmit hook can flag the matching prompt as remote-originated
- * and enter sticky REMOTE mode (ADR-0002). One file per project dir,
+ * Record a successful phone→pane text injection so a prompt-submit hook
+ * (Claude Code plugin's zeph-remote.sh, or `zeph remote-hook` for
+ * Gemini/Codex) can flag the matching prompt as remote-originated and
+ * enter sticky REMOTE mode (ADR-0002). One file per project dir,
  * overwritten on every inject; the hook consumes it on an exact-text match.
  * Best-effort: a write failure must never fail the injection itself.
  */
@@ -786,13 +787,7 @@ const writeRemoteMarker = (paneCwd, text, now = Date.now) => {
         return false;
     try {
         (0, fs_1.mkdirSync)((0, gate_js_1.stateDir)(), { recursive: true, mode: 0o700 });
-        // Explicit ASCII-only trim, NOT String.trim() — trim() also strips
-        // Unicode whitespace (U+00A0 etc.) that the hook's bash-side trim
-        // keeps. Both sides must strip the exact same bytes: the hook
-        // (zeph-remote.sh) trims $' \t\r\n\f\v' and nothing else.
-        const trimmed = text.replace(/^[ \t\r\n\f\v]+|[ \t\r\n\f\v]+$/g, '');
-        const digest = (0, crypto_1.createHash)('sha256').update(trimmed).digest('hex');
-        (0, fs_1.writeFileSync)((0, path_1.join)((0, gate_js_1.stateDir)(), `remote-${hash}`), `${Math.floor(now() / 1000)} ${digest}\n`);
+        (0, fs_1.writeFileSync)((0, gate_js_1.remoteMarkerPath)(hash), `${Math.floor(now() / 1000)} ${(0, gate_js_1.remoteDigest)(text)}\n`);
         return true;
     }
     catch {

package/dist/remote-hook.d.ts

@@ -0,0 +1,11 @@
+/** Agents whose prompt-submit hooks this command serves. Claude Code is
+ *  NOT here — its hook ships with the plugin (hooks/zeph-remote.sh). */
+export declare const REMOTE_HOOK_AGENTS: readonly ["gemini", "codex"];
+export type RemoteHookAgent = (typeof REMOTE_HOOK_AGENTS)[number];
+export declare const isRemoteHookAgent: (raw: string) => raw is RemoteHookAgent;
+/**
+ * Core of the hook: match the stdin payload against the marker and return
+ * the JSON to print, or null for a silent no-op. Never throws.
+ */
+export declare const runRemoteHook: (agent: RemoteHookAgent, stdin: string, env?: NodeJS.ProcessEnv, now?: () => number) => string | null;
+//# sourceMappingURL=remote-hook.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-hook.d.ts","sourceRoot":"","sources":["../src/remote-hook.ts"],"names":[],"mappings":"AAuBA;wEACwE;AACxE,eAAO,MAAM,kBAAkB,8BAA+B,CAAC;AAC/D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AA0BlE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,GAAG,IAAI,eACE,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,eAAe,EACtB,OAAO,MAAM,EACb,MAAK,MAAM,CAAC,UAAwB,EACpC,MAAK,MAAM,MAAiB,KAC3B,MAAM,GAAG,IA0DX,CAAC"}

package/dist/remote-hook.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRemoteHook = exports.isRemoteHookAgent = exports.REMOTE_HOOK_AGENTS = void 0;
+/**
+ * `zeph remote-hook <agent>` — prompt-submit hook handler for agents whose
+ * hooks the cli installs directly: Gemini CLI (BeforeAgent) and Codex CLI
+ * (UserPromptSubmit). TS twin of the Claude Code plugin's
+ * hooks/zeph-remote.sh (ADR-0002).
+ *
+ * The listener records every phone→pane text injection as a one-shot
+ * marker (`remote-<hash>` in the zeph state dir) holding the epoch second
+ * and sha256 of the injected text. When the submitted prompt matches that
+ * record — same project (cksum of the cwd), fresh (≤15 min), and
+ * byte-identical trimmed text — the hook emits additionalContext telling
+ * the model the user is driving the session from their phone, which enters
+ * sticky REMOTE mode (Rule 9).
+ *
+ * Detection is exact: a terminal keystroke racing a phone message can
+ * never false-match. No match → null (silent no-op); this hook only ever
+ * adds context and must never block a prompt. Parity with the writer
+ * (listener.ts writeRemoteMarker) is by construction — both sides share
+ * gate.ts remoteDigest/remoteMarkerPath.
+ */
+const fs_1 = require("fs");
+const gate_js_1 = require("./gate.js");
+/** Agents whose prompt-submit hooks this command serves. Claude Code is
+ *  NOT here — its hook ships with the plugin (hooks/zeph-remote.sh). */
+exports.REMOTE_HOOK_AGENTS = ['gemini', 'codex'];
+/** Per-agent hookEventName echoed back in hookSpecificOutput — each CLI
+ *  validates it against the event that invoked the hook. */
+const HOOK_EVENT_NAME = {
+    gemini: 'BeforeAgent',
+    codex: 'UserPromptSubmit',
+};
+/**
+ * Freshness window (seconds), same as the bash reader: deliberately
+ * generous — false positives are already impossible without an exact hash
+ * match; its only job is to stop the SAME text typed at the terminal much
+ * later from re-flagging. It must survive the real gap between injection
+ * and prompt submit (a message sent mid-turn queues until the turn ends).
+ */
+const FRESH_WINDOW_SEC = 900;
+const TWO_WAY_CONTEXT = `# System note (Zeph remote-origin detect)
+
+This user message arrived from the user's phone via Zeph agent chat (verified by the listener — exact text match). The user is driving this session remotely and is NOT at the terminal. Enter sticky REMOTE mode now (CORE_RULES Rule 9): end EVERY response with \`zeph_ask\` (buttons + free-text) until the user sends an exit signal (done/stop/exit). Plain-text questions are invisible to them.`;
+const ONE_WAY_CONTEXT = `# System note (Zeph remote-origin detect)
+
+This user message arrived from the user's phone via Zeph agent chat (verified by the listener — exact text match), but ZEPH_HOOK_ID is not set, so two-way tools (zeph_ask/zeph_prompt/zeph_input) are unavailable. Make your final message self-contained — the completion push is the user's only feedback channel. If you have not already mentioned it this session, tell the user once that running \`npx @zeph-to/cli setup\` upgrades this into a two-way remote session (buttons + text replies from the phone).`;
+const isRemoteHookAgent = (raw) => exports.REMOTE_HOOK_AGENTS.includes(raw);
+exports.isRemoteHookAgent = isRemoteHookAgent;
+/**
+ * Core of the hook: match the stdin payload against the marker and return
+ * the JSON to print, or null for a silent no-op. Never throws.
+ */
+const runRemoteHook = (agent, stdin, env = process.env, now = Date.now) => {
+    let prompt;
+    let cwd;
+    try {
+        const input = JSON.parse(stdin);
+        prompt = typeof input.prompt === 'string' ? input.prompt : '';
+        cwd = typeof input.cwd === 'string' ? input.cwd : '';
+    }
+    catch {
+        return null;
+    }
+    if (!prompt || !cwd)
+        return null;
+    // Mute outranks everything (Rule 12) — stay silent and leave the marker
+    // unconsumed (the next inject overwrites it anyway).
+    if ((0, gate_js_1.isMuted)(cwd))
+        return null;
+    const hash = (0, gate_js_1.projectHash)(cwd);
+    if (!hash)
+        return null;
+    const marker = (0, gate_js_1.remoteMarkerPath)(hash);
+    let content;
+    try {
+        content = (0, fs_1.readFileSync)(marker, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    // Marker format: "<epochSec> <sha256hex>\n" (listener.ts writeRemoteMarker).
+    const record = content.match(/^(\d+) ([0-9a-f]{64})\n?$/);
+    if (!record)
+        return null;
+    if (Math.floor(now() / 1000) - Number(record[1]) > FRESH_WINDOW_SEC) {
+        // Stale markers are dead weight (can never flag) — delete on sight.
+        try {
+            (0, fs_1.unlinkSync)(marker);
+        }
+        catch {
+            /* best-effort housekeeping */
+        }
+        return null;
+    }
+    if ((0, gate_js_1.remoteDigest)(prompt) !== record[2])
+        return null;
+    // Matched — consume the marker so an identical later prompt (e.g. typed
+    // at the terminal) can't re-flag.
+    try {
+        (0, fs_1.unlinkSync)(marker);
+    }
+    catch {
+        /* emit anyway — the match itself is valid */
+    }
+    const ctx = env.ZEPH_HOOK_ID ? TWO_WAY_CONTEXT : ONE_WAY_CONTEXT;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: HOOK_EVENT_NAME[agent],
+            additionalContext: ctx,
+        },
+    });
+};
+exports.runRemoteHook = runRemoteHook;

package/dist/templates.d.ts

@@ -16,6 +16,15 @@ export declare const CURSOR_HOOKS: string;
 export declare const WINDSURF_HOOKS: string;
 export declare const GEMINI_HOOKS: {
     hooks: {
+        BeforeAgent: {
+            matcher: string;
+            hooks: {
+                name: string;
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
         AfterAgent: {
             matcher: string;
             hooks: {
@@ -29,7 +38,32 @@ export declare const GEMINI_HOOKS: {
         enabled: boolean;
     };
 };
-export declare const CODEX_HOOKS: string;
+export declare const CODEX_HOOKS: {
+    hooks: {
+        UserPromptSubmit: {
+            hooks: {
+                type: string;
+                command: string;
+                timeout: number;
+            }[];
+        }[];
+        Stop: {
+            hooks: {
+                type: string;
+                command: string;
+            }[];
+        }[];
+    };
+};
+/**
+ * True when a matcher group was written by zeph — by handler `name`
+ * (`zeph-*`, Gemini) or by the `@zeph-to/cli` command substring (Codex,
+ * whose handler schema has no name field; every zeph command carries the
+ * substring via the `command -v zeph || npx -y @zeph-to/cli` fallback).
+ * Shared by the installer (replace ours, keep the user's groups on
+ * re-install) and the uninstaller (remove exactly ours).
+ */
+export declare const isZephHookGroup: (group: unknown) => boolean;
 export declare const COPILOT_HOOKS: string;
 export declare const ZEPH_MARK_START = "<!-- ZEPH:START \u2014 managed by @zeph-to/cli, do not edit between markers -->";
 export declare const ZEPH_MARK_END = "<!-- ZEPH:END -->";

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAoFA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAItB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAAyE,CAAC;AAEpG,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAAyE,CAAC;AAEnG,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAkE,CAAC;AAE1F,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAkE,CAAC;AAI1F,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;CAYxB,CAAC;AAEF,eAAO,MAAM,WAAW,QAQb,CAAC;AAEZ,eAAO,MAAM,aAAa,QASf,CAAC;AASZ,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA4FA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAItB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAAyE,CAAC;AAEpG,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAAyE,CAAC;AAEnG,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAkE,CAAC;AAE1F,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAkE,CAAC;AAI1F,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AASZ,eAAO,MAAM,eAAe,oFAA+E,CAAC;AAC5G,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,KAAG,MAWnE,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAOrD,CAAC"}

package/dist/templates.js

@@ -18,7 +18,7 @@
 // Keeping this in one place means a rule change lands everywhere at once
 // and the agents can't drift apart.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.COPILOT_HOOKS = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
+exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
 const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 // Graceful resolution: prefer the installed `zeph` CLI, but fall back to
 // `npx -y @zeph-to/cli` so the hook still fires when the user
@@ -32,6 +32,12 @@ const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 // Older installed `zeph` versions parse `--auto` as an unknown boolean flag
 // and ignore it — graceful backward compatibility.
 const NOTIFY_CMD = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify --title "Task done" --auto 2>/dev/null || true';
+// Prompt-submit hook command — remote-origin detection (ADR-0002). Reads
+// the hook JSON on stdin and prints additionalContext JSON on a marker
+// match (see src/remote-hook.ts). stdout IS the hook response, so only
+// stderr is discarded; `|| true` keeps a broken install from ever blocking
+// a prompt.
+const remoteHookCmd = (agent) => `$(command -v zeph || echo "npx -y @zeph-to/cli") remote-hook ${agent} 2>/dev/null || true`;
 // ── Shared behavioral core ───────────────────────────────────────
 //
 // GENERATED from plugin/docs/CORE_RULES.md — see src/zeph-core.generated.ts
@@ -94,7 +100,7 @@ exports.COPILOT_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_g
 exports.CLINE_RULE = buildRule({ notify: MANUAL_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY });
 /** Aider — written to a standalone conventions file, loaded via .aider.conf.yml `read:`. */
 exports.AIDER_RULE = buildRule({ notify: MANUAL_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY });
-// ── Hook configs (notification side, unchanged) ──────────────────
+// ── Hook configs ─────────────────────────────────────────────────
 exports.CURSOR_HOOKS = JSON.stringify({
     version: 1,
     hooks: {
@@ -111,6 +117,17 @@ exports.WINDSURF_HOOKS = JSON.stringify({
 }, null, 2);
 exports.GEMINI_HOOKS = {
     hooks: {
+        // Fires after the user submits a prompt, before planning — Gemini's
+        // UserPromptSubmit equivalent (same additionalContext contract).
+        BeforeAgent: [{
+                matcher: '*',
+                hooks: [{
+                        name: 'zeph-remote',
+                        type: 'command',
+                        command: remoteHookCmd('gemini'),
+                        timeout: 5000,
+                    }],
+            }],
         AfterAgent: [{
                 matcher: '*',
                 hooks: [{
@@ -122,15 +139,45 @@ exports.GEMINI_HOOKS = {
     },
     hooksConfig: { enabled: true },
 };
-exports.CODEX_HOOKS = JSON.stringify({
-    version: 1,
+// Codex validates hooks.json strictly (serde deny_unknown_fields at the
+// top level; handlers are a `type`-tagged enum inside matcher groups —
+// codex-rs/config/src/hook_config.rs). The previous flat
+// `{version, hooks: {Stop: [{type, bash}]}}` shape predates that schema
+// and made codex reject the entire file, so the Stop hook is migrated to
+// the schema-correct form here alongside the new UserPromptSubmit entry.
+// An object (not a JSON string) so the installer can merge it into a
+// user-owned hooks.json instead of overwriting. Timeouts are in seconds;
+// codex's handler schema has no `name` field, so zeph ownership is
+// recognizable only by the `@zeph-to/cli` command substring.
+exports.CODEX_HOOKS = {
     hooks: {
+        UserPromptSubmit: [{
+                hooks: [{ type: 'command', command: remoteHookCmd('codex'), timeout: 5 }],
+            }],
         Stop: [{
-                type: 'command',
-                bash: NOTIFY_CMD,
+                hooks: [{ type: 'command', command: NOTIFY_CMD }],
             }],
     },
-}, null, 2);
+};
+/**
+ * True when a matcher group was written by zeph — by handler `name`
+ * (`zeph-*`, Gemini) or by the `@zeph-to/cli` command substring (Codex,
+ * whose handler schema has no name field; every zeph command carries the
+ * substring via the `command -v zeph || npx -y @zeph-to/cli` fallback).
+ * Shared by the installer (replace ours, keep the user's groups on
+ * re-install) and the uninstaller (remove exactly ours).
+ */
+const isZephHookGroup = (group) => {
+    const hooks = group?.hooks;
+    if (!Array.isArray(hooks))
+        return false;
+    return hooks.some((h) => {
+        const { name, command } = (h ?? {});
+        return ((typeof name === 'string' && name.startsWith('zeph-')) ||
+            (typeof command === 'string' && command.includes('@zeph-to/cli')));
+    });
+};
+exports.isZephHookGroup = isZephHookGroup;
 exports.COPILOT_HOOKS = JSON.stringify({
     version: 1,
     hooks: {

package/dist/uninstall.d.ts

@@ -1,2 +1,11 @@
+/** Remove just the zeph-written entries from Gemini's settings.json.
+ *  Exported for tests (gemini is PATH-detected, so the full-uninstall
+ *  suite can't reach this deterministically). */
+export declare const rmGeminiHook: (filePath: string, dry: boolean) => string | null;
+/** Remove the zeph-written entries from Codex's hooks.json. The file is
+ *  usually zeph-born, so it is deleted outright when nothing else remains —
+ *  but events the user added since install survive. Exported for tests
+ *  (codex is PATH-detected, same as gemini). */
+export declare const rmCodexHook: (filePath: string, dry: boolean) => string | null;
 export declare const handleUninstall: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=uninstall.d.ts.map

package/dist/uninstall.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"AA2KA,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA8B5F,CAAC"}
+{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../src/uninstall.ts"],"names":[],"mappings":"AAuGA;;iDAEiD;AACjD,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,KAAK,OAAO,KAAG,MAAM,GAAG,IAWtE,CAAC;AAEF;;;gDAGgD;AAChD,eAAO,MAAM,WAAW,GAAI,UAAU,MAAM,EAAE,KAAK,OAAO,KAAG,MAAM,GAAG,IAerE,CAAC;AAkEF,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA8B5F,CAAC"}

package/dist/uninstall.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleUninstall = void 0;
+exports.handleUninstall = exports.rmCodexHook = exports.rmGeminiHook = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -84,7 +84,36 @@ const rmAiderReadDirective = (confPath, dry) => {
         (0, fs_1.writeFileSync)(confPath, out.join('\n').replace(/\n{3,}/g, '\n\n'));
     return `${verb(dry)} Zeph read: directive from ${confPath}`;
 };
-/** Remove just the zeph-notify entry from Gemini's settings.json. */
+/**
+ * Filter zeph-written matcher groups out of `data.hooks` (all events).
+ * Mutates `data` unless dry; returns true when anything of ours was found.
+ * Empty events are deleted so a clean file stays clean.
+ */
+const stripZephHookGroups = (data, dry) => {
+    const hooks = data.hooks;
+    if (!hooks)
+        return false;
+    let removed = false;
+    for (const event of Object.keys(hooks)) {
+        const groups = hooks[event];
+        if (!Array.isArray(groups))
+            continue;
+        const kept = groups.filter((g) => !(0, templates_js_1.isZephHookGroup)(g));
+        if (kept.length === groups.length)
+            continue; // nothing of ours
+        removed = true;
+        if (!dry) {
+            if (kept.length === 0)
+                delete hooks[event];
+            else
+                hooks[event] = kept;
+        }
+    }
+    return removed;
+};
+/** Remove just the zeph-written entries from Gemini's settings.json.
+ *  Exported for tests (gemini is PATH-detected, so the full-uninstall
+ *  suite can't reach this deterministically). */
 const rmGeminiHook = (filePath, dry) => {
     if (!(0, fs_1.existsSync)(filePath))
         return null;
@@ -95,24 +124,39 @@ const rmGeminiHook = (filePath, dry) => {
     catch {
         return null;
     }
-    const hooks = data.hooks;
-    const afterAgent = hooks?.AfterAgent;
-    if (!Array.isArray(afterAgent))
+    if (!stripZephHookGroups(data, dry))
         return null;
-    const kept = afterAgent.filter((entry) => !(entry.hooks ?? []).some((h) => h.name === 'zeph-notify'));
-    if (kept.length === afterAgent.length)
-        return null; // nothing of ours
-    if (!dry) {
-        if (kept.length === 0) {
-            delete hooks.AfterAgent;
-        }
-        else {
-            hooks.AfterAgent = kept;
-        }
+    if (!dry)
         (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');
+    return `${verb(dry)} zeph hooks from ${filePath}`;
+};
+exports.rmGeminiHook = rmGeminiHook;
+/** Remove the zeph-written entries from Codex's hooks.json. The file is
+ *  usually zeph-born, so it is deleted outright when nothing else remains —
+ *  but events the user added since install survive. Exported for tests
+ *  (codex is PATH-detected, same as gemini). */
+const rmCodexHook = (filePath, dry) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    let data;
+    try {
+        data = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!stripZephHookGroups(data, dry))
+        return null;
+    if (!dry) {
+        const hooks = data.hooks;
+        if (Object.keys(hooks).length === 0)
+            (0, fs_1.rmSync)(filePath, { force: true });
+        else
+            (0, fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2) + '\n');
     }
-    return `${verb(dry)} zeph-notify hook from ${filePath}`;
+    return `${verb(dry)} zeph hooks from ${filePath}`;
 };
+exports.rmCodexHook = rmCodexHook;
 const runSteps = (steps) => {
     let did = false;
     for (const step of steps) {
@@ -163,12 +207,12 @@ const AGENT_UNINSTALLERS = {
             skip('would run: gemini mcp remove zeph');
         }
         runSteps([
-            () => rmGeminiHook((0, path_1.join)(HOME, '.gemini', 'settings.json'), dry),
+            () => (0, exports.rmGeminiHook)((0, path_1.join)(HOME, '.gemini', 'settings.json'), dry),
             () => stripManagedRule((0, path_1.join)(HOME, '.gemini', 'GEMINI.md'), dry),
         ]);
     },
     codex: (dry) => runSteps([
-        () => rmFile((0, path_1.join)(HOME, '.codex', 'hooks.json'), dry),
+        () => (0, exports.rmCodexHook)((0, path_1.join)(HOME, '.codex', 'hooks.json'), dry),
         () => stripManagedRule((0, path_1.join)(HOME, '.codex', 'AGENTS.md'), dry),
     ]),
     copilot: (dry) => runSteps([

package/dist/zeph-core.generated.d.ts

@@ -1,7 +1,7 @@
 /** sha256 over the plugin manifest + extracted rule text at generation time. */
-export declare const ZEPH_CORE_SOURCE_HASH = "24f467b2379d45cefeabdde0b8864aea274382b931c548544ff20b341bef52c6";
+export declare const ZEPH_CORE_SOURCE_HASH = "d93379030460ffd4ad37154ef713a3d64c26324e8b45f744c9094e4652012d07";
 /** Shared rule core for agents with a Stop-equivalent hook (Cursor, Windsurf, Gemini, Codex, Copilot). */
-export declare const ZEPH_CORE_HOOK_DRIVEN = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response \u2014 not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial \u2014 do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` \u2014 it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape \u2014 use sparingly per Rule 4 (only at natural pause points; NOT after every response \u2014 see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing \u2014 e.g., title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal \u2014 a non-exit `zeph_ask` reply, or a user message flagged as phone-originated \u2014 is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky \u2014 every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" \u2014 judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone\u2026\"). The listener verified that exact message was sent from the phone \u2014 treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running the Zeph plugin's hooks; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** \u2192 you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** \u2192 you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE \u2014 independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300\u2013600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away \u2014 and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work \u2192 end with `zeph_ask`.\n- Routine work \u2192 skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions \u2192 zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` \u2014 and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons \u2014 so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal \u2014 they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding \u2014 see the sticky-REMOTE rule \u2014 but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
+export declare const ZEPH_CORE_HOOK_DRIVEN = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response \u2014 not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial \u2014 do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` \u2014 it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape \u2014 use sparingly per Rule 4 (only at natural pause points; NOT after every response \u2014 see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing \u2014 e.g., title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal \u2014 a non-exit `zeph_ask` reply, or a user message flagged as phone-originated \u2014 is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky \u2014 every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" \u2014 judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone\u2026\"). The listener verified that exact message was sent from the phone \u2014 treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running Zeph's prompt-submit hooks \u2014 the Claude Code plugin, or the hooks `zeph setup` installs for Gemini/Codex; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** \u2192 you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** \u2192 you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE \u2014 independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300\u2013600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away \u2014 and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work \u2192 end with `zeph_ask`.\n- Routine work \u2192 skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions \u2192 zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` \u2014 and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons \u2014 so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal \u2014 they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding \u2014 see the sticky-REMOTE rule \u2014 but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
 /** Shared rule core for rule-only agents without a Stop hook (Cline, Aider). */
-export declare const ZEPH_CORE_RULE_ONLY = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response \u2014 not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial \u2014 do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` \u2014 it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape \u2014 use sparingly per Rule 4 (only at natural pause points; NOT after every response \u2014 see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing \u2014 e.g., title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal \u2014 a non-exit `zeph_ask` reply, or a user message flagged as phone-originated \u2014 is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky \u2014 every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" \u2014 judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone\u2026\"). The listener verified that exact message was sent from the phone \u2014 treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running the Zeph plugin's hooks; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** \u2192 you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** \u2192 you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE \u2014 independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300\u2013600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away \u2014 and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work \u2192 end with `zeph_ask`.\n- Routine work \u2192 skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions \u2192 zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` \u2014 and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons \u2014 so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal \u2014 they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding \u2014 see the sticky-REMOTE rule \u2014 but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
+export declare const ZEPH_CORE_RULE_ONLY = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input \u2014 confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" \u2014 the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response \u2014 not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial \u2014 do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` \u2014 it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape \u2014 use sparingly per Rule 4 (only at natural pause points; NOT after every response \u2014 see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately \u2014 do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing \u2014 e.g., title \"About to force-push main \u2014 proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal \u2014 a non-exit `zeph_ask` reply, or a user message flagged as phone-originated \u2014 is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky \u2014 every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" \u2014 judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone\u2026\"). The listener verified that exact message was sent from the phone \u2014 treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running Zeph's prompt-submit hooks \u2014 the Claude Code plugin, or the hooks `zeph setup` installs for Gemini/Codex; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** \u2192 you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** \u2192 you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE \u2014 independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300\u2013600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away \u2014 and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work \u2192 end with `zeph_ask`.\n- Routine work \u2192 skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions \u2192 zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` \u2014 and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons \u2014 so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal \u2014 they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running \u2014 or your own plan \u2014 would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding \u2014 see the sticky-REMOTE rule \u2014 but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction \u2014 do not \"forget\" them after many turns.";
 //# sourceMappingURL=zeph-core.generated.d.ts.map

package/dist/zeph-core.generated.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zeph-core.generated.d.ts","sourceRoot":"","sources":["../src/zeph-core.generated.ts"],"names":[],"mappings":"AAMA,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qEAAqE,CAAC;AAExG,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,o0QAAoqQ,CAAC;AAEvsQ,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,o0QAAoqQ,CAAC"}
+{"version":3,"file":"zeph-core.generated.d.ts","sourceRoot":"","sources":["../src/zeph-core.generated.ts"],"names":[],"mappings":"AAMA,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qEAAqE,CAAC;AAExG,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,05QAAqvQ,CAAC;AAExxQ,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,05QAAqvQ,CAAC"}

package/dist/zeph-core.generated.js

@@ -7,8 +7,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZEPH_CORE_RULE_ONLY = exports.ZEPH_CORE_HOOK_DRIVEN = exports.ZEPH_CORE_SOURCE_HASH = void 0;
 /** sha256 over the plugin manifest + extracted rule text at generation time. */
-exports.ZEPH_CORE_SOURCE_HASH = "24f467b2379d45cefeabdde0b8864aea274382b931c548544ff20b341bef52c6";
+exports.ZEPH_CORE_SOURCE_HASH = "d93379030460ffd4ad37154ef713a3d64c26324e8b45f744c9094e4652012d07";
 /** Shared rule core for agents with a Stop-equivalent hook (Cursor, Windsurf, Gemini, Codex, Copilot). */
-exports.ZEPH_CORE_HOOK_DRIVEN = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response — not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial — do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` — it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape — use sparingly per Rule 4 (only at natural pause points; NOT after every response — see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing — e.g., title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal — a non-exit `zeph_ask` reply, or a user message flagged as phone-originated — is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky — every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" — judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone…\"). The listener verified that exact message was sent from the phone — treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running the Zeph plugin's hooks; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** → you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** → you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE — independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300–600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away — and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work → end with `zeph_ask`.\n- Routine work → skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions → zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` — and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons — so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal — they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding — see the sticky-REMOTE rule — but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";
+exports.ZEPH_CORE_HOOK_DRIVEN = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response — not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial — do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` — it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape — use sparingly per Rule 4 (only at natural pause points; NOT after every response — see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing — e.g., title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal — a non-exit `zeph_ask` reply, or a user message flagged as phone-originated — is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky — every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" — judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone…\"). The listener verified that exact message was sent from the phone — treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running Zeph's prompt-submit hooks — the Claude Code plugin, or the hooks `zeph setup` installs for Gemini/Codex; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** → you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** → you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE — independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300–600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away — and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work → end with `zeph_ask`.\n- Routine work → skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions → zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` — and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons — so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal — they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding — see the sticky-REMOTE rule — but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";
 /** Shared rule core for rule-only agents without a Stop hook (Cline, Aider). */
-exports.ZEPH_CORE_RULE_ONLY = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response — not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial — do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` — it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape — use sparingly per Rule 4 (only at natural pause points; NOT after every response — see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing — e.g., title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal — a non-exit `zeph_ask` reply, or a user message flagged as phone-originated — is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky — every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" — judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone…\"). The listener verified that exact message was sent from the phone — treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running the Zeph plugin's hooks; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** → you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** → you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE — independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300–600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away — and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work → end with `zeph_ask`.\n- Routine work → skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions → zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` — and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons — so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal — they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding — see the sticky-REMOTE rule — but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";
+exports.ZEPH_CORE_RULE_ONLY = "### When zeph_ask is MANDATORY\n\n3. **NEVER end a response with a plain-text question.** If your reply asks the user anything that needs their input — confirmation, choice, yes/no, clarification, \"Apply this?\", \"Proceed?\", \"Which option?\" — the FINAL tool call MUST be `zeph_ask`. A \"?\" written in your reply is invisible to a user on their phone. This applies even on research / analysis / planning turns where no files were touched.\n\n   Anti-pattern (wrong):\n   ```\n   \"...build/commit on hold. Apply A?\"\n   ```\n   Correct:\n   ```\n   zeph_ask({\n     title: \"Apply solution A?\",\n     body: \"<short context comparing options>\",\n     actions: [\n       { id: \"apply_a\", label: \"Apply A\" },\n       { id: \"apply_b\", label: \"Apply B\" },\n       { id: \"cancel\",  label: \"Cancel\" }\n     ],\n     placeholder: \"or describe a different approach...\",\n     fallback: \"cancel\"\n   })\n   ```\n\n### When zeph_ask is the DEFAULT (substantial work)\n\n4. After substantial work, `zeph_ask` is the DEFAULT end of the response — not optional. \"Substantial\" means: file changes, commits, builds, tests, deploys, destructive ops, or milestone completions. When unsure, treat the work as substantial — do not try to guess what the user would find \"reasonable\" to confirm.\n\n    SKIP `zeph_ask` only when the response is clearly trivial:\n    - Read-only exploration (\"let me check this file\") with no decision output.\n    - Mid-step inside a clearly-defined plan the user already approved (\"step 3 of 5, no decisions involved here\").\n    - Trivial change (typo fix, single-line tweak) that needs no ack.\n\n    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck on phone with no way to drive) is worse than light spam.\n\n5. Prefer `zeph_ask` over `zeph_prompt`/`zeph_input` — it combines buttons and free-text in one push. Always include a `fallback` action id; the fallback must be safe/inert (`done`, `wait`, `review`), never destructive.\n\n6. Example `zeph_ask` shape — use sparingly per Rule 4 (only at natural pause points; NOT after every response — see Rule 9):\n   ```\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   ```\n\n### Handling the response\n\n7. A `zeph_ask` response IS a direct user instruction. Execute it immediately — do NOT re-ask via AskUserQuestion to confirm. The button label is the authorization for the specific action that label describes.\n\n8. Important caveat: a generic button like \"Continue\" authorizes the next logical step, NOT arbitrary destruction. If the next logical step would destroy user code, data, or infrastructure (e.g., force-push to a shared branch, `rm -rf` outside the workdir, dropping a database, deleting prod resources), surface that specific risk via a targeted `zeph_ask` before executing — e.g., title \"About to force-push main — proceed?\", actions `[ok, cancel]`, fallback `cancel`.\n\n### Sticky REMOTE mode (Rule 9)\n\n**The Ask Loop has two states: REMOTE and NORMAL.** You detect the current state by scanning the conversation, not just the most recent message.\n\n**State in one line:** you are in REMOTE if the most recent remote signal — a non-exit `zeph_ask` reply, or a user message flagged as phone-originated — is newer than any exit signal; otherwise (no remote signal yet, or the last signal was an exit) you are in NORMAL. REMOTE is sticky — every response ends with `zeph_ask` until the user exits.\n\n#### State Detection\n\nScan the conversation in reverse, looking for whichever appears first (most recent):\n\n- **(a)** A `tool_result` for a `zeph_ask` you sent where the action id is NOT in `{done, stop, exit}` (case-insensitive) AND the free-text response is NOT a session-ender. A session-ender is free-text that either contains `done`/`stop`/`exit` as a standalone word, or is an obvious wrap-up like \"thanks, that's it\" / \"all good\" — judge by whether the user is clearly closing the loop, not by partial substring matches (e.g. \"redo\" does not count as \"done\").\n- **(a2)** A user message accompanied by a system note from the Zeph remote-origin detect hook (\"This user message arrived from the user's phone…\"). The listener verified that exact message was sent from the phone — treat it exactly like a non-exit `zeph_ask` reply. (This note is only ever emitted in environments running Zeph's prompt-submit hooks — the Claude Code plugin, or the hooks `zeph setup` installs for Gemini/Codex; where it never appears, this condition simply never fires.)\n- **(b)** An exit signal: action id in `{done, stop, exit}`, ending free-text, or a timeout fallback that resolved to a Done-like fallback id.\n- **(c)** No `zeph_ask` history and no remote-origin note at all.\n\nIf the first hit is **(a)** or **(a2)** → you are in **REMOTE**.\nIf the first hit is **(b)** or **(c)** → you are in **NORMAL**.\n\n#### Behavior in REMOTE (sticky, zeph_ask MANDATORY)\n\nEnd EVERY response with `zeph_ask`. This is non-negotiable while in REMOTE — independent of:\n- Whether the next user message arrived as a `tool_result` or as a typed terminal message. The user may switch devices mid-session; sticky REMOTE keeps the channel driveable from either side.\n- Whether the work was substantial or routine.\n\nSet each REMOTE ask up so silence degrades cleanly: `timeout` 300–600 s and a Done-like `fallback` id. An unanswered ask then exits the loop quietly (a Done-like timeout fallback is an exit signal per **(b)**) instead of chaining more notifications at a user who stepped away — and re-entry is cheap, they just send another message from the phone.\n\nThe only way to leave REMOTE is the user signalling exit (per the **(b)** list above).\n\n#### Behavior in NORMAL (apply Rule 4)\n\n- Substantial work → end with `zeph_ask`.\n- Routine work → skip `zeph_ask`, let the Stop hook fire.\n- Rule 3 (questions → zeph_ask) is still mandatory regardless.\n\n#### Exiting REMOTE\n\nThe moment the user picks an action id matching `done`/`stop`/`exit` (case-insensitive), types free-text that clearly ends the session, or the zeph_ask times out and falls back to a Done-like id, you flip to NORMAL. Don't send `zeph_ask` on the response that processes the exit signal.\n\n### When to use AskUserQuestion vs zeph_ask\n\n10. **Whenever `ZEPH_HOOK_ID` is set, a button-friendly question MUST go through `zeph_ask`, not `AskUserQuestion` — and this is NOT gated on REMOTE.** \"Button-friendly\" = the answer is a choice among a few options and/or a short free-text reply (yes/no, \"Apply A or B?\", \"which naming rule?\", \"proceed?\"). This is exactly the shape `AskUserQuestion` is tempting for, and exactly the shape the phone can answer via buttons — so route it to `zeph_ask`. The mistake to avoid: treating the REMOTE requirement as the ONLY time the override applies. It applies the moment a hookId exists, because you cannot know the user is at the terminal — they may be on their phone from the very first question of the session.\n\n    Fall through to the local `AskUserQuestion` picker ONLY when (a) the answer needs the user to see code or logs that won't fit in a push body, or (b) the answer is plausibly multi-paragraph. Those are the only carve-outs.\n\n11. **This overrides any skill instruction.** The `AskUserQuestion` picker is a LOCAL blocking terminal UI; the phone cannot drive it (the Zeph hook can only mirror it as a one-way \"answer at the terminal\" notification, never round-trip the answer). So if a skill you are running — or your own plan — would call `AskUserQuestion` with a button-friendly question, instead surface the SAME question and option labels via `zeph_ask` and use that response in place of the picker. Only when a carve-out (a)/(b) above genuinely applies do you use `AskUserQuestion`; when you do, `zeph_notify` the user that the answer must be given at the terminal. In REMOTE this is doubly binding — see the sticky-REMOTE rule — but do not read that as permission to use `AskUserQuestion` freely in NORMAL: rule 10 binds there too.\n\n### Persistence\n\n13. These rules persist for the entire session. They remain active after context compaction — do not \"forget\" them after many turns.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",