@zeph-to/cli 1.17.0 → 1.19.0

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

@@ -1 +1 @@
-{"version":3,"file":"remote-agents.d.ts","sourceRoot":"","sources":["../src/remote-agents.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3E;AAyCD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAaF,UAAU,gBAAgB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACf;AAkDD,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACnC,SAAS,MAAM,EACf,SAAS,MAAM,GAAG,IAAI,EACtB,OAAM,cAAmB,KAC1B,MAAM,GAAG,IAOX,CAAC;AAIF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;EAwBmB,CAAC;AAE5C,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,8FAA8F;AAC9F,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,SAAS,qBAAqB,EAAuB,CAAC;AAElF,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,qBAAqB,GAAG,SAClB,CAAC;AAE3D,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,qBAAqB,GAAG,SAG9E,CAAC"}
+{"version":3,"file":"remote-agents.d.ts","sourceRoot":"","sources":["../src/remote-agents.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,WAAW;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CAC3E;AAyCD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAaF,UAAU,gBAAgB;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACf;AA4ED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACnC,SAAS,MAAM,EACf,SAAS,MAAM,GAAG,IAAI,EACtB,OAAM,cAAmB,KAC1B,MAAM,GAAG,IAOX,CAAC;AAIF,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;EAwBmB,CAAC;AAE5C,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,8FAA8F;AAC9F,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtE,eAAO,MAAM,aAAa,EAAE,SAAS,qBAAqB,EAAuB,CAAC;AAElF,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,qBAAqB,GAAG,SAClB,CAAC;AAE3D,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,qBAAqB,GAAG,SAG9E,CAAC"}

package/dist/remote-agents.js

@@ -112,15 +112,25 @@ const readPidSessionRecords = () => {
         return []; // dir absent (older CC) — caller falls back to mtime
     }
 };
-/** pid set of `rootPid` + all descendants, from one `ps` snapshot. */
-const collectDescendantPids = (rootPid, psOutput) => {
-    let table = psOutput;
-    if (table === undefined) {
-        const r = (0, child_process_1.spawnSync)('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-        if (r.status !== 0)
-            return new Set([rootPid]);
-        table = r.stdout ?? '';
-    }
+// One `ps` spawn and one ~/.claude/sessions scan per report cycle, not per
+// tmux session: the resolver runs for every session every 5s, and each call
+// paid a full process-table spawn plus a directory scan on the daemon's hot
+// path. A TTL just under the report interval lets all sessions in one cycle
+// share a single snapshot while still refreshing every cycle. The parsed
+// child-adjacency map is what's cached (not the raw table) so N sessions
+// share one parse and differ only in the per-root BFS.
+const SNAPSHOT_TTL_MS = 4_000;
+const ttlMemo = (ttlMs, compute) => {
+    let snap = null;
+    return () => {
+        const now = Date.now();
+        if (snap && snap.expiresAt > now)
+            return snap.value;
+        snap = { value: compute(), expiresAt: now + ttlMs };
+        return snap.value;
+    };
+};
+const parseChildren = (table) => {
     const children = new Map();
     for (const line of table.split('\n')) {
         const m = line.trim().match(/^(\d+)\s+(\d+)$/);
@@ -131,6 +141,18 @@ const collectDescendantPids = (rootPid, psOutput) => {
         list.push(pid);
         children.set(ppid, list);
     }
+    return children;
+};
+const readPsChildren = ttlMemo(SNAPSHOT_TTL_MS, () => {
+    const r = (0, child_process_1.spawnSync)('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return r.status === 0 ? parseChildren(r.stdout ?? '') : null;
+});
+const cachedPidSessionRecords = ttlMemo(SNAPSHOT_TTL_MS, readPidSessionRecords);
+/** pid set of `rootPid` + all descendants, from one `ps` snapshot. */
+const collectDescendantPids = (rootPid, psOutput) => {
+    const children = psOutput !== undefined ? parseChildren(psOutput) : readPsChildren();
+    if (children === null)
+        return new Set([rootPid]);
     const found = new Set([rootPid]);
     const queue = [rootPid];
     while (queue.length > 0) {
@@ -150,7 +172,7 @@ const collectDescendantPids = (rootPid, psOutput) => {
  * to the mtime heuristic.
  */
 const detectClaudeSessionIdByPid = (panePid, paneCwd, deps = {}) => {
-    const records = deps.records ?? readPidSessionRecords();
+    const records = deps.records ?? cachedPidSessionRecords();
     if (records.length === 0)
         return null;
     const descendants = deps.descendants ?? collectDescendantPids(panePid);

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 = "5d149a2909f9d1da7544fe4fcf540700c1be14193290d6f55e503a46032d8155";
+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 `zeph_ask` response was a non-exit reply; otherwise (no `zeph_ask` history, or the last one was an exit signal) 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- **(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 at all.\n\nIf the first hit is **(a)** \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\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 `zeph_ask` response was a non-exit reply; otherwise (no `zeph_ask` history, or the last one was an exit signal) 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- **(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 at all.\n\nIf the first hit is **(a)** \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\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,y7OAAuzO,CAAC;AAE11O,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,y7OAAuzO,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"}