@zeph-to/cli 1.13.2 → 1.15.0

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.15.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": {