@zeph-to/cli 1.13.2 → 1.14.0

package/dist/cli.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const fs_1 = require("fs");
 const child_process_1 = require("child_process");
 const zeph_hook_js_1 = require("./zeph-hook.js");
 const errors_js_1 = require("./errors.js");
@@ -13,21 +12,10 @@ const check_update_js_1 = require("./check-update.js");
 const wrapper_js_1 = require("./wrapper.js");
 const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
-const PROJECT_DIR_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
-const detectProjectDir = () => PROJECT_DIR_VARS.reduce((found, key) => found || process.env[key], undefined) ?? process.cwd();
-const isMuted = () => {
-    try {
-        const dir = detectProjectDir();
-        const raw = (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' });
-        const hash = raw.split(' ')[0];
-        return (0, fs_1.existsSync)(`/tmp/zeph-muted-${hash}`);
-    }
-    catch {
-        return false;
-    }
-};
+const gate_js_1 = require("./gate.js");
+const remote_agents_js_1 = require("./remote-agents.js");
 const detectBranchAndProject = () => {
-    const dir = detectProjectDir();
+    const dir = (0, config_js_1.detectProjectDir)();
     const project = dir.split('/').filter(Boolean).pop() ?? 'project';
     let branch;
     try {
@@ -67,6 +55,8 @@ const parseArgs = (argv) => {
     return result;
 };
 // ── Output ──────────────────────────────────────────────────────
+/** One usage line per registered remote agent — generated so help text can't drift from the table. */
+const usageAgentLines = () => remote_agents_js_1.REMOTE_AGENTS.map((a) => `  ${`${a.subcommands[0]} [args…]`.padEnd(15)} Run '${a.binary}' in a named tmux session ('zeph-<project>')`).join('\n');
 const printUsage = () => {
     console.log(`Usage: zeph <command> [options]
 
@@ -80,9 +70,7 @@ Commands:
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
   test            Send a test notification to verify setup
-  cc [args…]      Run 'claude' in a named tmux session ('zeph-<project>')
-  codex [args…]   Run 'codex' in a named tmux session
-  gemini [args…]  Run 'gemini' in a named tmux session
+${usageAgentLines()}
                   (auto-suffixed -2/-3/… when another zeph cc is already
                    attached to the default name; any args after the
                    subcommand are forwarded verbatim, e.g.
@@ -99,6 +87,11 @@ Notify options:
   --priority <p>     Priority (low|normal|high|urgent) [default: normal]
   --device <id>      Target device ID
   --session <id>     AI session ID (or set ZEPH_SESSION_ID env)
+  --auto             Apply the push gate before sending (honors the
+                     /zeph-quiet | /zeph-loud dial; silent exit when gated)
+  --marker <m>       Push Signal marker for --auto (skip|push|high)
+  --tools <n>        Turn tool count for --auto [default: assume real work]
+  --nonreadonly <n>  Non-read-only tool count for --auto
 
 List options:
   --limit <n>        Number of pushes (1-20, default 5)
@@ -166,10 +159,33 @@ const createHook = (args) => {
         ...(baseUrl && { baseUrl }),
     });
 };
+/** Parse a gate count flag; garbage input falls back to the default (never accidentally silences). */
+const gateCount = (raw, fallback) => {
+    const n = typeof raw === 'string' ? Number(raw) : NaN;
+    return Number.isFinite(n) && n >= 0 ? n : fallback;
+};
 const handleNotify = async (args) => {
     const isJson = args.json === true;
-    if (isMuted())
+    const projectDir = (0, config_js_1.detectProjectDir)();
+    if ((0, gate_js_1.isMuted)(projectDir))
         return 0;
+    // --auto: apply the shared push-gate before sending. Inputs default to
+    // GATE_DEFAULTS ("assume real work") so dumb hooks keep their historical
+    // always-push behavior in normal mode, while the /zeph-quiet | /zeph-loud
+    // dial now works for every hook-driven agent. Gated-out → silent success.
+    if (args.auto === true) {
+        const verdict = (0, gate_js_1.decidePush)({
+            toolCount: gateCount(args.tools, gate_js_1.GATE_DEFAULTS.toolCount),
+            nonReadonlyCount: gateCount(args.nonreadonly, gate_js_1.GATE_DEFAULTS.nonReadonlyCount),
+            alreadyAsked: gate_js_1.GATE_DEFAULTS.alreadyAsked,
+            marker: (0, gate_js_1.normalizeMarker)(typeof args.marker === 'string' ? args.marker : undefined),
+            pushMode: (0, gate_js_1.readPushMode)(projectDir),
+        });
+        if (!verdict.push)
+            return 0;
+        if (verdict.priority === 'high' && !args.priority)
+            args.priority = 'high';
+    }
     const hook = createHook(args);
     if (!hook)
         return 3;
@@ -337,6 +353,12 @@ const main = async () => {
         printUsage();
         return 0;
     }
+    // Remote-control subcommands (`zeph cc` / `zeph codex` / …) come from the
+    // registry — one table row per agent, no hardcoded cases. Pass the typed
+    // command token to collectPassthrough (aliases map to the same agent).
+    const remote = (0, remote_agents_js_1.findAgentBySubcommand)(command);
+    if (remote)
+        return (0, wrapper_js_1.handleAgentSession)(remote, collectPassthrough(process.argv, command));
     switch (command) {
         case 'install':
         case 'setup':
@@ -357,12 +379,6 @@ const main = async () => {
             return handleDismiss(args);
         case 'test':
             return handleTest(args);
-        case 'cc':
-            return (0, wrapper_js_1.handleAgentSession)('claude', collectPassthrough(process.argv, 'cc'));
-        case 'codex':
-            return (0, wrapper_js_1.handleAgentSession)('codex', collectPassthrough(process.argv, 'codex'));
-        case 'gemini':
-            return (0, wrapper_js_1.handleAgentSession)('gemini', collectPassthrough(process.argv, 'gemini'));
         case 'listener':
             return (0, listener_js_1.handleListener)(args);
         default:

package/dist/config.d.ts

@@ -8,6 +8,9 @@ export interface ZephConfig {
     deviceId?: string;
 }
 export declare const resolvedEnv: (key: string) => string | undefined;
+export declare const PROJECT_DIR_ENV_VARS: readonly ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "WINDSURF_PROJECT_DIR"];
+/** First set project-dir env (unresolved `${VAR}` placeholders ignored), else cwd. */
+export declare const detectProjectDir: () => string;
 export declare const loadConfig: () => ZephConfig;
 export declare const saveConfig: (config: ZephConfig) => void;
 export declare const VERSION: string;

package/dist/config.d.ts.map

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

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.saveConfig = exports.loadConfig = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
+exports.VERSION = exports.saveConfig = exports.loadConfig = exports.detectProjectDir = exports.PROJECT_DIR_ENV_VARS = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -11,6 +11,21 @@ const resolvedEnv = (key) => {
     return val && !val.startsWith('${') ? val : undefined;
 };
 exports.resolvedEnv = resolvedEnv;
+// Per-agent project-dir env vars, in precedence order. Deliberately NOT part
+// of the remote-agent registry: Cursor/Windsurf carry project-dir envs but
+// are not remote-controllable via tmux — the two tables have different
+// membership.
+exports.PROJECT_DIR_ENV_VARS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
+/** First set project-dir env (unresolved `${VAR}` placeholders ignored), else cwd. */
+const detectProjectDir = () => {
+    for (const key of exports.PROJECT_DIR_ENV_VARS) {
+        const val = (0, exports.resolvedEnv)(key);
+        if (val)
+            return val;
+    }
+    return process.cwd();
+};
+exports.detectProjectDir = detectProjectDir;
 const loadConfig = () => {
     try {
         return JSON.parse((0, fs_1.readFileSync)(exports.CONFIG_FILE, 'utf-8'));

package/dist/gate.d.ts

@@ -0,0 +1,36 @@
+export type GateMarker = 'skip' | 'push' | 'high' | 'none';
+export type GatePushMode = 'quiet' | 'loud' | 'normal';
+export interface GateInput {
+    /** Total tool_use blocks this turn. */
+    toolCount: number;
+    /** Tools that are NOT read-only (Read/Grep/Glob). */
+    nonReadonlyCount: number;
+    /** A zeph_ask/zeph_prompt already notified this turn. */
+    alreadyAsked: boolean;
+    marker: GateMarker;
+    pushMode: GatePushMode;
+}
+export interface GateVerdict {
+    push: boolean;
+    priority: 'high' | 'normal';
+}
+/**
+ * "Assume real work" defaults for hooks that can't supply turn facts
+ * (most non-Claude agents pass no counts): in normal mode the push still
+ * fires — preserving the historical always-push behavior of the dumb
+ * hooks — while quiet/loud now work everywhere.
+ */
+export declare const GATE_DEFAULTS: {
+    readonly toolCount: 2;
+    readonly nonReadonlyCount: 1;
+    readonly alreadyAsked: false;
+};
+export declare const normalizeMarker: (raw: string | undefined) => GateMarker;
+export declare const normalizePushMode: (raw: string | undefined) => GatePushMode;
+export declare const decidePush: (input: GateInput) => GateVerdict;
+export declare const projectHash: (dir: string) => string | null;
+/** 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. */
+export declare const readPushMode: (dir: string) => GatePushMode;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAsBA,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;AAQF,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,YAQ1C,CAAC"}

package/dist/gate.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPushMode = exports.isMuted = exports.projectHash = exports.decidePush = exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = void 0;
+/**
+ * Push-gate decision — the portable half of the Zeph Stop-hook logic.
+ *
+ * `decidePush` is the TS twin of `plugin/hooks/gate.sh` (zeph-to/plugin).
+ * Both implementations are locked to the same semantics by the shared
+ * vector file `src/fixtures/gate-vectors.json` (vendored from the plugin
+ * repo's canonical copy via `npm run sync:plugin`): the bash side and this
+ * side run the exact same cases in their CIs, so a semantic change to one
+ * that isn't mirrored in the other fails a build. Edit them together.
+ *
+ * Ordering is contractual (encoded as named vectors):
+ *   1. alreadyAsked wins over EVERYTHING — even loud (dedup beats the dial).
+ *   2. priority is high iff marker === 'high', decided BEFORE the mode
+ *      switch, so quiet+high and loud+high both push at high priority.
+ *   3. quiet → only a high marker pushes; loud → always push; normal →
+ *      marker overrides the heuristic (skip → silent, push/high → push),
+ *      no marker → push iff toolCount ≥ 2 AND nonReadonlyCount > 0
+ *      (the B1 read-only floor).
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+/**
+ * "Assume real work" defaults for hooks that can't supply turn facts
+ * (most non-Claude agents pass no counts): in normal mode the push still
+ * fires — preserving the historical always-push behavior of the dumb
+ * hooks — while quiet/loud now work everywhere.
+ */
+exports.GATE_DEFAULTS = {
+    toolCount: 2,
+    nonReadonlyCount: 1,
+    alreadyAsked: false,
+};
+const normalizeMarker = (raw) => raw === 'skip' || raw === 'push' || raw === 'high' ? raw : 'none';
+exports.normalizeMarker = normalizeMarker;
+const normalizePushMode = (raw) => raw === 'quiet' || raw === 'loud' ? raw : 'normal';
+exports.normalizePushMode = normalizePushMode;
+const decidePush = (input) => {
+    if (input.alreadyAsked)
+        return { push: false, priority: 'normal' };
+    const priority = input.marker === 'high' ? 'high' : 'normal';
+    if (input.pushMode === 'quiet')
+        return { push: input.marker === 'high', priority };
+    if (input.pushMode === 'loud')
+        return { push: true, priority };
+    if (input.marker === 'skip')
+        return { push: false, priority };
+    if (input.marker === 'push' || input.marker === 'high')
+        return { push: true, priority };
+    return { push: input.toolCount >= 2 && input.nonReadonlyCount > 0, priority };
+};
+exports.decidePush = decidePush;
+// ── Per-project gate state (mute + push-mode dial) ───────────────
+//
+// The plugin's bash hooks key these tmp files off `cksum` of the project
+// dir; shelling out to the same `cksum` here (instead of a pure-TS CRC)
+// guarantees hash parity with every already-written file.
+const projectHash = (dir) => {
+    try {
+        const raw = (0, child_process_1.execFileSync)('cksum', { input: dir, encoding: 'utf-8' });
+        return raw.split(' ')[0] || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.projectHash = projectHash;
+/** True when the user ran /zeph-mute for this project. */
+const isMuted = (dir) => {
+    const hash = (0, exports.projectHash)(dir);
+    return hash !== null && (0, fs_1.existsSync)(`/tmp/zeph-muted-${hash}`);
+};
+exports.isMuted = isMuted;
+/** The user's session push-mode dial (/zeph-quiet | /zeph-loud), default normal. */
+const readPushMode = (dir) => {
+    const hash = (0, exports.projectHash)(dir);
+    if (!hash)
+        return 'normal';
+    try {
+        return (0, exports.normalizePushMode)((0, fs_1.readFileSync)(`/tmp/zeph-pushmode-${hash}`, 'utf-8').replace(/\s+/g, ''));
+    }
+    catch {
+        return 'normal';
+    }
+};
+exports.readPushMode = readPushMode;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { ZephHook } from './zeph-hook.js';
 export { ZephError, AuthenticationError, QuotaExceededError } from './errors.js';
 export type { ZephOptions, NotifyPayload, NotifyResult, ListParams, ListResult, DismissOneResult, DismissAllResult, PushItem } from './types.js';
+export { decidePush, GATE_DEFAULTS, normalizeMarker, normalizePushMode } from './gate.js';
+export type { GateInput, GateVerdict, GateMarker, GatePushMode } from './gate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjF,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACjJ,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC1F,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,9 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QuotaExceededError = exports.AuthenticationError = exports.ZephError = exports.ZephHook = void 0;
+exports.normalizePushMode = exports.normalizeMarker = exports.GATE_DEFAULTS = exports.decidePush = exports.QuotaExceededError = exports.AuthenticationError = exports.ZephError = exports.ZephHook = void 0;
 var zeph_hook_js_1 = require("./zeph-hook.js");
 Object.defineProperty(exports, "ZephHook", { enumerable: true, get: function () { return zeph_hook_js_1.ZephHook; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ZephError", { enumerable: true, get: function () { return errors_js_1.ZephError; } });
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
 Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_js_1.QuotaExceededError; } });
+var gate_js_1 = require("./gate.js");
+Object.defineProperty(exports, "decidePush", { enumerable: true, get: function () { return gate_js_1.decidePush; } });
+Object.defineProperty(exports, "GATE_DEFAULTS", { enumerable: true, get: function () { return gate_js_1.GATE_DEFAULTS; } });
+Object.defineProperty(exports, "normalizeMarker", { enumerable: true, get: function () { return gate_js_1.normalizeMarker; } });
+Object.defineProperty(exports, "normalizePushMode", { enumerable: true, get: function () { return gate_js_1.normalizePushMode; } });

package/dist/listener.d.ts

@@ -20,7 +20,7 @@
  * messages as new pushes are created. Reconnects with exponential
  * backoff on transient failures; gives up on auth failures (4001/4002/4003).
  */
-type AgentKind = 'claude' | 'codex' | 'gemini';
+import { type AgentKind, type RegisteredRemoteAgent } from './remote-agents.js';
 interface AgentSession {
     name: string;
     attached: boolean;
@@ -55,15 +55,22 @@ export declare const parseSessionName: (name: string) => {
     project: string;
     label: string | null;
 } | null;
+interface PaneInfo {
+    currentCommand: string | null;
+    startCommand: string | null;
+    currentPath: string | null;
+}
 /**
- * Locate the most recent Claude Code session UUID for the working
- * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
- * detectClaudeSessionId: CC writes per-session jsonl files at
- * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
- * the cwd with `/` replaced by `-`. Cached for 60s — see
- * claudeSessionCache.
+ * Identify the agent from the tmux pane. Prefer `pane_start_command`
+ * because the foreground process is usually `node`/`python3` (the
+ * interpreter), which doesn't tell us *what* was launched. Fall back to
+ * `pane_current_command` when start_command is empty — tmux clears
+ * start_command in some re-attach cases, especially when a pre-existing
+ * session was joined via `tmux new -A` instead of being created fresh.
+ * That fallback is safe because only the literal binaries registered in
+ * remote-agents.ts are accepted as a match.
  */
-export declare const detectClaudeSessionId: (cwd: string) => string | null;
+export declare const detectRemoteAgent: (info: PaneInfo) => RegisteredRemoteAgent | null;
 export interface CollectResult {
     sessions: AgentSession[];
     /** Diagnostic notes per rejected session — surfaced under `--verbose`. */
@@ -81,11 +88,12 @@ export interface CollectResult {
 export declare const collectSessionsVerbose: () => CollectResult;
 /**
  * Snapshot the live `zeph-*` tmux sessions on this machine, enriched
- * with the running agent kind, CC session UUID (claude only), project,
- * and tmux activity timestamps. Returns [] when tmux is unreachable
- * or no agent sessions exist. Sessions whose pane is at a shell or
- * running something other than claude/codex/gemini are filtered out
- * — the phone can't usefully address them.
+ * with the running agent kind, the agent's own session id (when the
+ * registry has a resolver — currently Claude Code only), project, and
+ * tmux activity timestamps. Returns [] when tmux is unreachable or no
+ * agent sessions exist. Sessions whose pane is at a shell or running
+ * something not registered in remote-agents.ts are filtered out — the
+ * phone can't usefully address them.
  */
 export declare const collectSessions: () => AgentSession[];
 /**

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

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleListener = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.collectSessions = exports.collectSessionsVerbose = exports.detectClaudeSessionId = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = void 0;
+exports.handleListener = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.collectSessions = exports.collectSessionsVerbose = exports.detectRemoteAgent = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -33,6 +33,7 @@ const os_1 = require("os");
 const path_1 = require("path");
 const ws_1 = __importDefault(require("ws"));
 const config_js_1 = require("./config.js");
+const remote_agents_js_1 = require("./remote-agents.js");
 const PING_INTERVAL_MS = 25_000;
 const PONG_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_MS = 1_000;
@@ -54,7 +55,6 @@ const WS_STALL_TIMEOUT_MS = 90_000;
 // to reflect new `zeph cc` sessions within a few seconds, not half a
 // minute.
 const SESSION_REPORT_INTERVAL_MS = 5_000;
-const AGENT_KINDS = ['claude', 'codex', 'gemini'];
 // Per-session token bucket — caps a runaway/compromised sender. 30/min
 // is generous for human-driven phone use, tight enough to block flooding.
 const RATE_LIMIT_TOKENS = 30;
@@ -400,70 +400,6 @@ const parseSessionName = (name) => {
     return { project: rest, label: null };
 };
 exports.parseSessionName = parseSessionName;
-const CLAUDE_PROJECTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.claude', 'projects');
-/**
- * Cache for detectClaudeSessionId. The function walks every jsonl file
- * in `~/.claude/projects/<hash>/` on each call — after weeks of CC use
- * that directory holds hundreds of session files, and we were calling
- * this per tmux session per 5-second report cycle. Heavy disk I/O
- * compounded with multiple sessions caused the report cycle to spike
- * CPU and starve the host shell.
- *
- * The current-session UUID only changes when a new CC session starts
- * in that directory (rare, on the order of hours), so a 60-second TTL
- * is safe and cuts the per-cycle stat count by ~12×.
- */
-const claudeSessionCache = new Map();
-const CLAUDE_SESSION_CACHE_TTL_MS = 60_000;
-const doDetectClaudeSessionId = (cwd) => {
-    try {
-        const projectHash = cwd.replace(/\//g, '-');
-        const sessionsDir = (0, path_1.join)(CLAUDE_PROJECTS_DIR, projectHash);
-        let latest;
-        for (const entry of (0, fs_1.readdirSync)(sessionsDir)) {
-            const m = entry.match(/^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/);
-            if (!m)
-                continue;
-            const stat = (0, fs_1.statSync)((0, path_1.join)(sessionsDir, entry));
-            if (!stat.isFile())
-                continue;
-            if (!latest || stat.mtimeMs > latest.mtime) {
-                latest = { name: m[1], mtime: stat.mtimeMs };
-            }
-        }
-        return latest?.name ?? null;
-    }
-    catch {
-        return null;
-    }
-};
-/**
- * Locate the most recent Claude Code session UUID for the working
- * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
- * detectClaudeSessionId: CC writes per-session jsonl files at
- * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
- * the cwd with `/` replaced by `-`. Cached for 60s — see
- * claudeSessionCache.
- */
-const detectClaudeSessionId = (cwd) => {
-    const now = Date.now();
-    const cached = claudeSessionCache.get(cwd);
-    if (cached && cached.expiresAt > now)
-        return cached.sessionId;
-    // Cap cache size so a long-lived listener that's seen many cwds
-    // doesn't grow unbounded. 64 is plenty for any realistic setup.
-    if (claudeSessionCache.size >= 64) {
-        // Evict the oldest-expiring entry — Map iteration order is
-        // insertion order, so the first key we hit is the oldest.
-        const firstKey = claudeSessionCache.keys().next().value;
-        if (firstKey !== undefined)
-            claudeSessionCache.delete(firstKey);
-    }
-    const sessionId = doDetectClaudeSessionId(cwd);
-    claudeSessionCache.set(cwd, { sessionId, expiresAt: now + CLAUDE_SESSION_CACHE_TTL_MS });
-    return sessionId;
-};
-exports.detectClaudeSessionId = detectClaudeSessionId;
 // U+241F "Symbol for Unit Separator" — a *printable* Unicode glyph
 // (3-byte UTF-8) that visually represents the C0 Unit Separator but is
 // itself a normal character. Critical detail: tmux 3.5a's `-F` format
@@ -509,28 +445,19 @@ const firstTokenBasename = (cmd) => {
     return (0, path_1.basename)(stripped.split(/\s+/)[0] || '');
 };
 /**
- * Identify the agent type from the tmux pane. Prefer `pane_start_command`
+ * Identify the agent from the tmux pane. Prefer `pane_start_command`
  * because the foreground process is usually `node`/`python3` (the
  * interpreter), which doesn't tell us *what* was launched. Fall back to
  * `pane_current_command` when start_command is empty — tmux clears
  * start_command in some re-attach cases, especially when a pre-existing
  * session was joined via `tmux new -A` instead of being created fresh.
- * That fallback is safe because we only accept literal `claude` /
- * `codex` / `gemini` as a match.
+ * That fallback is safe because only the literal binaries registered in
+ * remote-agents.ts are accepted as a match.
  */
-const detectAgentKind = (info) => {
-    const startBase = firstTokenBasename(info.startCommand);
-    for (const k of AGENT_KINDS) {
-        if (startBase === k)
-            return k;
-    }
-    const currentBase = firstTokenBasename(info.currentCommand);
-    for (const k of AGENT_KINDS) {
-        if (currentBase === k)
-            return k;
-    }
-    return null;
-};
+const detectRemoteAgent = (info) => (0, remote_agents_js_1.matchAgentByPaneCommand)(firstTokenBasename(info.startCommand))
+    ?? (0, remote_agents_js_1.matchAgentByPaneCommand)(firstTokenBasename(info.currentCommand))
+    ?? null;
+exports.detectRemoteAgent = detectRemoteAgent;
 const epochToIso = (epoch) => {
     if (!epoch)
         return undefined;
@@ -583,21 +510,21 @@ const collectSessionsVerbose = () => {
             continue;
         }
         const info = readPaneInfo(name);
-        const agentKind = detectAgentKind(info);
-        if (!agentKind) {
+        const agent = (0, exports.detectRemoteAgent)(info);
+        if (!agent) {
             rejected.push({
                 name,
                 reason: `no agent in pane (start=${info.startCommand ?? 'null'}, current=${info.currentCommand ?? 'null'})`,
             });
             continue;
         }
-        const agentSessionId = agentKind === 'claude' && info.currentPath
-            ? (0, exports.detectClaudeSessionId)(info.currentPath)
+        const agentSessionId = info.currentPath
+            ? (agent.resolveSessionId?.(info.currentPath) ?? null)
             : null;
         sessions.push({
             name,
             attached: attached === '1',
-            agentKind,
+            agentKind: agent.kind,
             agentSessionId,
             project: parsed.project,
             label: parsed.label,
@@ -610,11 +537,12 @@ const collectSessionsVerbose = () => {
 exports.collectSessionsVerbose = collectSessionsVerbose;
 /**
  * Snapshot the live `zeph-*` tmux sessions on this machine, enriched
- * with the running agent kind, CC session UUID (claude only), project,
- * and tmux activity timestamps. Returns [] when tmux is unreachable
- * or no agent sessions exist. Sessions whose pane is at a shell or
- * running something other than claude/codex/gemini are filtered out
- * — the phone can't usefully address them.
+ * with the running agent kind, the agent's own session id (when the
+ * registry has a resolver — currently Claude Code only), project, and
+ * tmux activity timestamps. Returns [] when tmux is unreachable or no
+ * agent sessions exist. Sessions whose pane is at a shell or running
+ * something not registered in remote-agents.ts are filtered out — the
+ * phone can't usefully address them.
  */
 const collectSessions = () => (0, exports.collectSessionsVerbose)().sessions;
 exports.collectSessions = collectSessions;

package/dist/remote-agents.d.ts

@@ -0,0 +1,55 @@
+export interface RemoteAgent {
+    /** Wire value for AgentSession.agentKind (server/phone contract). */
+    kind: string;
+    /** Human name for --help text. */
+    displayName: string;
+    /** Binary launched in the tmux pane; also the primary pane-match token. */
+    binary: string;
+    /** `zeph <subcommand>` aliases that launch this agent. */
+    subcommands: readonly string[];
+    /** Extra pane_command basenames accepted as this agent (beyond binary). */
+    paneMatchAliases?: readonly string[];
+    /**
+     * Resolve the agent's own session id from the pane's cwd.
+     * EXTENSION POINT: omitted for codex/gemini until their session-file
+     * formats are confirmed — the listener then reports agentSessionId: null.
+     */
+    resolveSessionId?: (paneCwd: string) => string | null;
+}
+/**
+ * Locate the most recent Claude Code session UUID for the working
+ * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
+ * detectClaudeSessionId: CC writes per-session jsonl files at
+ * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
+ * the cwd with `/` replaced by `-`. Cached for 60s — see
+ * claudeSessionCache.
+ */
+export declare const detectClaudeSessionId: (cwd: string) => string | null;
+declare const REMOTE_AGENT_TABLE: readonly [{
+    readonly kind: "claude";
+    readonly displayName: "Claude Code";
+    readonly binary: "claude";
+    readonly subcommands: readonly ["cc", "claude"];
+    readonly resolveSessionId: (cwd: string) => string | null;
+}, {
+    readonly kind: "codex";
+    readonly displayName: "Codex CLI";
+    readonly binary: "codex";
+    readonly subcommands: readonly ["codex"];
+}, {
+    readonly kind: "gemini";
+    readonly displayName: "Gemini CLI";
+    readonly binary: "gemini";
+    readonly subcommands: readonly ["gemini"];
+}];
+/** Closed union of remote-controllable agent kinds ('claude' | 'codex' | 'gemini'). */
+export type AgentKind = (typeof REMOTE_AGENT_TABLE)[number]['kind'];
+/** A registry row: the uniform RemoteAgent shape with `kind` narrowed to the closed union. */
+export type RegisteredRemoteAgent = RemoteAgent & {
+    kind: AgentKind;
+};
+export declare const REMOTE_AGENTS: readonly RegisteredRemoteAgent[];
+export declare const findAgentBySubcommand: (cmd: string) => RegisteredRemoteAgent | undefined;
+export declare const matchAgentByPaneCommand: (base: string) => RegisteredRemoteAgent | undefined;
+export {};
+//# sourceMappingURL=remote-agents.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"remote-agents.d.ts","sourceRoot":"","sources":["../src/remote-agents.ts"],"names":[],"mappings":"AAiBA,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;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACzD;AAyCD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAiB5D,CAAC;AAIF,QAAA,MAAM,kBAAkB;;;;;qCArBmB,MAAM,KAAG,MAAM,GAAG,IAAI;;;;;;;;;;;EAyCtB,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

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchAgentByPaneCommand = exports.findAgentBySubcommand = exports.REMOTE_AGENTS = exports.detectClaudeSessionId = void 0;
+/**
+ * Remote-control agent registry — the single table behind `zeph cc` /
+ * `zeph codex` / `zeph gemini`, the listener's pane matching, and the
+ * per-agent session-id enrichment. Adding a remote-controllable agent is
+ * one row here (plus, for a genuinely new kind, backend/phone support:
+ * `kind` is a wire contract — AgentSession.agentKind flows to the server
+ * and the phone picker, which may validate the enum).
+ *
+ * This is deliberately NOT merged into `agents.ts`: that table drives
+ * install/uninstall/verify detection (8 agents, incl. Cursor/Windsurf
+ * which can never be driven via tmux), and the two tables carry different
+ * name axes — install id vs subcommand alias vs pane binary.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+// ── Claude Code session resolver ─────────────────────────────────
+const CLAUDE_PROJECTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.claude', 'projects');
+/**
+ * Cache for detectClaudeSessionId. The function walks every jsonl file
+ * in `~/.claude/projects/<hash>/` on each call — after weeks of CC use
+ * that directory holds hundreds of session files, and we were calling
+ * this per tmux session per 5-second report cycle. Heavy disk I/O
+ * compounded with multiple sessions caused the report cycle to spike
+ * CPU and starve the host shell.
+ *
+ * The current-session UUID only changes when a new CC session starts
+ * in that directory (rare, on the order of hours), so a 60-second TTL
+ * is safe and cuts the per-cycle stat count by ~12×.
+ */
+const claudeSessionCache = new Map();
+const CLAUDE_SESSION_CACHE_TTL_MS = 60_000;
+const doDetectClaudeSessionId = (cwd) => {
+    try {
+        const projectHash = cwd.replace(/\//g, '-');
+        const sessionsDir = (0, path_1.join)(CLAUDE_PROJECTS_DIR, projectHash);
+        let latest;
+        for (const entry of (0, fs_1.readdirSync)(sessionsDir)) {
+            const m = entry.match(/^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/);
+            if (!m)
+                continue;
+            const stat = (0, fs_1.statSync)((0, path_1.join)(sessionsDir, entry));
+            if (!stat.isFile())
+                continue;
+            if (!latest || stat.mtimeMs > latest.mtime) {
+                latest = { name: m[1], mtime: stat.mtimeMs };
+            }
+        }
+        return latest?.name ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Locate the most recent Claude Code session UUID for the working
+ * directory of a tmux pane. Mirrors `mcp-server/config.ts`'s
+ * detectClaudeSessionId: CC writes per-session jsonl files at
+ * `~/.claude/projects/<projectHash>/<UUID>.jsonl` where the hash is
+ * the cwd with `/` replaced by `-`. Cached for 60s — see
+ * claudeSessionCache.
+ */
+const detectClaudeSessionId = (cwd) => {
+    const now = Date.now();
+    const cached = claudeSessionCache.get(cwd);
+    if (cached && cached.expiresAt > now)
+        return cached.sessionId;
+    // Cap cache size so a long-lived listener that's seen many cwds
+    // doesn't grow unbounded. 64 is plenty for any realistic setup.
+    if (claudeSessionCache.size >= 64) {
+        // Evict the oldest-expiring entry — Map iteration order is
+        // insertion order, so the first key we hit is the oldest.
+        const firstKey = claudeSessionCache.keys().next().value;
+        if (firstKey !== undefined)
+            claudeSessionCache.delete(firstKey);
+    }
+    const sessionId = doDetectClaudeSessionId(cwd);
+    claudeSessionCache.set(cwd, { sessionId, expiresAt: now + CLAUDE_SESSION_CACHE_TTL_MS });
+    return sessionId;
+};
+exports.detectClaudeSessionId = detectClaudeSessionId;
+// ── The registry ─────────────────────────────────────────────────
+const REMOTE_AGENT_TABLE = [
+    {
+        kind: 'claude',
+        displayName: 'Claude Code',
+        binary: 'claude',
+        subcommands: ['cc', 'claude'],
+        resolveSessionId: exports.detectClaudeSessionId,
+    },
+    {
+        kind: 'codex',
+        displayName: 'Codex CLI',
+        binary: 'codex',
+        subcommands: ['codex'],
+    },
+    {
+        kind: 'gemini',
+        displayName: 'Gemini CLI',
+        binary: 'gemini',
+        subcommands: ['gemini'],
+    },
+];
+exports.REMOTE_AGENTS = REMOTE_AGENT_TABLE;
+const findAgentBySubcommand = (cmd) => exports.REMOTE_AGENTS.find((a) => a.subcommands.includes(cmd));
+exports.findAgentBySubcommand = findAgentBySubcommand;
+const matchAgentByPaneCommand = (base) => {
+    if (!base)
+        return undefined;
+    return exports.REMOTE_AGENTS.find((a) => a.binary === base || (a.paneMatchAliases ?? []).includes(base));
+};
+exports.matchAgentByPaneCommand = matchAgentByPaneCommand;

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAgNA,6EAA6E;AAC7E,eAAO,MAAM,WAAW,QAGtB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,aAAa,QAA4C,CAAC;AAEvE,sDAAsD;AACtD,eAAO,MAAM,WAAW,QAA4C,CAAC;AAErE,oDAAoD;AACpD,eAAO,MAAM,UAAU,QAA4C,CAAC;AAEpE,oFAAoF;AACpF,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE,gEAAgE;AAChE,eAAO,MAAM,UAAU,QAAuC,CAAC;AAE/D,4FAA4F;AAC5F,eAAO,MAAM,UAAU,QAAuC,CAAC;AAI/D,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":"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"}

package/dist/templates.js

@@ -3,7 +3,8 @@
 //
 // Every supported agent gets the SAME behavioral rules so Zeph behaves
 // identically everywhere. The rule text is assembled from one shared
-// core (ZEPH_CORE) plus a per-agent notification preamble:
+// generated core (src/zeph-core.generated.ts) plus a per-agent
+// notification preamble:
 //
 //   - Hook-driven agents (Cursor, Windsurf, Gemini, Codex, Copilot) have
 //     a Stop-equivalent hook installed that auto-pushes on completion, so
@@ -12,160 +13,31 @@
 //     zeph_notify for meaningful completions.
 //
 // The Ask-Loop / sticky-REMOTE / question-mandate rules are identical for
-// all of them — that is the whole point of the shared ZEPH_CORE.
+// all of them — that is the whole point of the shared generated core.
 //
 // 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;
+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
 // installed via a non-standard prefix and the binary isn't on PATH at hook
 // fire time (e.g. ~/.local/bin without PATH update). This mirrors the
 // pattern in plugin/hooks/zeph-{stop,ask}.sh.
-const NOTIFY_CMD = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify --title "Task done" 2>/dev/null || true';
-// ── Shared behavioral core ───────────────────────────────────────
 //
-// Identical across every agent. Source of truth: plugin/docs/CORE_RULES.md
-// Do not fork this per-agent — if a rule needs to differ, it belongs in
-// the per-agent preamble instead.
+// `--auto` applies the shared push-gate before sending (see src/gate.ts):
+// in normal mode the push still fires (gate defaults assume real work), but
+// the /zeph-quiet | /zeph-loud dial now works for every hook-driven agent.
+// 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';
+// ── Shared behavioral core ───────────────────────────────────────
 //
-// Last synced: 2026-06-26
-// To update: extract rules from plugin/docs/CORE_RULES.md and sync here.
-const ZEPH_CORE = `## When zeph_ask is MANDATORY
-
-When ZEPH_HOOK_ID is set the user is driving you remotely, often from
-their phone. A "?" written in your reply text is invisible to them.
-
-3. NEVER end a response with a plain-text question. If your response 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. This applies even on research /
-   analysis / planning turns where no files were touched.
-
-   Anti-pattern (wrong):
-     "...build/commit on hold. Apply A?"
-   Correct:
-     zeph_ask({
-       title: "Apply solution A?",
-       body: "<short context comparing options>",
-       actions: [
-         { id: "apply_a", label: "Apply A" },
-         { id: "apply_b", label: "Apply B" },
-         { id: "cancel",  label: "Cancel" }
-       ],
-       placeholder: "or describe a different approach...",
-       fallback: "cancel"
-     })
-
-## When zeph_ask is the DEFAULT (substantial work)
-
-4. 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.
-
-    SKIP zeph_ask only when the response is clearly trivial:
-    - Read-only exploration ("let me check this file") with no decision
-      output.
-    - Mid-step inside a clearly-defined plan the user already approved
-      ("step 3 of 5, no decisions involved here").
-    - Trivial change (typo fix, single-line tweak) that needs no ack.
-
-    When unsure: LEAN TOWARD ASKING. Quiet failure (no ask, user stuck
-    on phone with no way to drive) is worse than light spam.
-
-5. 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.
-
-6. Example zeph_ask shape:
-     zeph_ask({
-       title: "Done. Next?",
-       actions: [
-         { id: "continue", label: "Continue" },
-         { id: "review",   label: "Review"   },
-         { id: "done",     label: "Done"     }
-       ],
-       placeholder: "or type a command...",
-       fallback: "done"
-     })
-
-## Handling the response
-
-7. A zeph_ask response IS a direct user instruction. Execute it immediately —
-   do NOT re-ask via confirmation. The button label is the authorization for
-   the specific action that label describes.
-
-8. 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 (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.
-
-## Sticky REMOTE mode
-
-9. The Ask Loop has two states — REMOTE and NORMAL — detected by scanning the
-   conversation in reverse for whichever appears first:
-
-   (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 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" is not "done").
-       → You are in REMOTE.
-
-   (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.
-       → You are in NORMAL.
-
-   (c) No zeph_ask history at all.
-       → You are in NORMAL.
-
-   ### Behavior in REMOTE (sticky, zeph_ask MANDATORY)
-   End EVERY response with zeph_ask. This is non-negotiable while in REMOTE —
-   independent of:
-   - 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.
-   - Whether the work was substantial or routine.
-
-   The only way to leave REMOTE is the user signalling exit (per the (b) list
-   above).
-
-   ### Behavior in NORMAL (apply Rule 4)
-   - Substantial work → end with zeph_ask.
-   - Routine work → skip zeph_ask, let the Stop hook fire.
-   - Rule 3 (questions → zeph_ask) is still mandatory regardless.
-
-   ### Exiting REMOTE
-   The 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.
-
-## When to use AskUserQuestion vs zeph_ask
-
-10. Prefer zeph_ask for short remote-friendly questions. Use the local
-   AskUserQuestion tool 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.
-
-11. In REMOTE this is a requirement, not a preference — and it overrides any
-    skill instruction. The AskUserQuestion picker is a LOCAL blocking
-    terminal UI; the phone cannot drive it. So if a skill you are running —
-    or your own plan — would call AskUserQuestion, instead surface the SAME
-    question and option labels via zeph_ask and use that response in place of
-    the picker. Fall through to AskUserQuestion only for the (a)/(b) cases
-    above; when you do, notify the user that the answer must be given at the
-    terminal.
-
-## Persistence
-
-These rules persist for the entire session. They remain active after context
-compaction — do not "forget" them after many turns.`;
+// GENERATED from plugin/docs/CORE_RULES.md — see src/zeph-core.generated.ts
+// (regenerate with `npm run sync:plugin`). Do not fork per-agent — if a rule
+// needs to differ, it belongs in the per-agent preamble instead, or in the
+// audience classification in the plugin repo's core-rules.manifest.json.
 // Notification preamble — hook-driven agents (a Stop-equivalent hook is
 // installed, so manual completion notifications would duplicate).
 const HOOK_DRIVEN_NOTIFY = `## Notification discipline
@@ -196,27 +68,32 @@ the user.
 
 ${opts.notify}
 
-${ZEPH_CORE}
+${opts.core}
 `;
 };
 // ── Per-agent rule documents ─────────────────────────────────────
+//
+// The two generated cores are identical today; the split exists so a rule
+// that only applies to one audience (e.g. Push Signal, once hook-driven
+// agents' hooks process markers) is a one-line manifest change upstream.
 /** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). */
 exports.CURSOR_RULE = buildRule({
     frontmatter: '---\ndescription: "Zeph remote-control rules"\nalwaysApply: true\n---',
     notify: HOOK_DRIVEN_NOTIFY,
+    core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN,
 });
 /** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. */
-exports.WINDSURF_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+exports.WINDSURF_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN });
 /** Gemini CLI — appended into ~/.gemini/GEMINI.md. */
-exports.GEMINI_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+exports.GEMINI_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN });
 /** Codex CLI — appended into ~/.codex/AGENTS.md. */
-exports.CODEX_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+exports.CODEX_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN });
 /** GitHub Copilot CLI — written to ~/.copilot/instructions/zeph.instructions.md. */
-exports.COPILOT_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY });
+exports.COPILOT_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN });
 /** Cline — written to ~/.cline/rules/zeph.md (no Stop hook). */
-exports.CLINE_RULE = buildRule({ notify: MANUAL_NOTIFY });
+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 });
+exports.AIDER_RULE = buildRule({ notify: MANUAL_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY });
 // ── Hook configs (notification side, unchanged) ──────────────────
 exports.CURSOR_HOOKS = JSON.stringify({
     version: 1,

package/dist/wrapper.d.ts

@@ -1,3 +1,4 @@
+import type { RemoteAgent } from './remote-agents.js';
 /** Resolve a project name for the tmux session: env > git root > cwd basename. */
 export declare const detectProjectName: () => string;
 /** `zeph-<project>` — the canonical tmux session base name. */
@@ -22,5 +23,5 @@ export declare const findAvailableSession: (base: string) => string;
  * `zeph cc --resume foo` runs `claude --resume foo` inside the session.
  * Returns when the agent exits.
  */
-export declare const handleAgentSession: (agent: string, extra?: string[]) => Promise<number>;
+export declare const handleAgentSession: (agent: RemoteAgent, extra?: string[]) => Promise<number>;
 //# sourceMappingURL=wrapper.d.ts.map

package/dist/wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAwBA,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AA6HF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmCtF,CAAC"}
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AA6HF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,WAAW,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmC3F,CAAC"}

package/dist/wrapper.js

@@ -16,15 +16,14 @@ const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
-/** First non-empty value among the supported per-agent project dir env vars. */
-const PROJECT_DIR_ENVS = ['CLAUDE_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'WINDSURF_PROJECT_DIR'];
+const config_js_1 = require("./config.js");
 const FALLBACK_NAME = 'project';
 /** basename(), with a stable fallback for edge paths like `/`. */
 const safeBasename = (path) => (0, path_1.basename)(path) || FALLBACK_NAME;
 /** Resolve a project name for the tmux session: env > git root > cwd basename. */
 const detectProjectName = () => {
-    for (const key of PROJECT_DIR_ENVS) {
-        const v = process.env[key];
+    for (const key of config_js_1.PROJECT_DIR_ENV_VARS) {
+        const v = (0, config_js_1.resolvedEnv)(key);
         if (v)
             return safeBasename(v.replace(/\/+$/, ''));
     }
@@ -206,7 +205,7 @@ const handleAgentSession = (agent, extra = []) => {
     // command for the picker on their phone to work.
     ensureListenerRunning();
     return new Promise((resolve) => {
-        const { cmd, args } = targetForAgent(agent, extra);
+        const { cmd, args } = targetForAgent(agent.binary, extra);
         const start = Date.now();
         const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'inherit' });
         child.on('exit', (code) => {

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

@@ -0,0 +1,7 @@
+/** sha256 over the plugin manifest + extracted rule text at generation time. */
+export declare const ZEPH_CORE_SOURCE_HASH = "5d149a2909f9d1da7544fe4fcf540700c1be14193290d6f55e503a46032d8155";
+/** 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.";
+/** 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.";
+//# sourceMappingURL=zeph-core.generated.d.ts.map

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

@@ -0,0 +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"}

package/dist/zeph-core.generated.js

@@ -0,0 +1,14 @@
+"use strict";
+// GENERATED by scripts/sync-from-plugin.mjs — DO NOT EDIT.
+// Source of truth: zeph-to/plugin docs/CORE_RULES.md, sliced per
+// scripts/core-rules.manifest.json. Regenerate with `npm run sync:plugin`
+// (requires a zeph-to/plugin checkout, sibling ../plugin by default).
+// CI cross-checks this file against plugin main and fails on drift.
+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 = "5d149a2909f9d1da7544fe4fcf540700c1be14193290d6f55e503a46032d8155";
+/** 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 `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 — 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- **(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)** → 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\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 `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 — 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- **(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)** → 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\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.13.2",
+  "version": "1.14.0",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -24,6 +24,7 @@
     "build": "tsc",
     "test": "vitest run",
     "test:watch": "vitest",
+    "sync:plugin": "node scripts/sync-from-plugin.mjs",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {