@zeph-to/cli 2.16.0 → 2.17.1

package/README.md

@@ -154,7 +154,10 @@ other way in: a `zeph_ask` answer that is not a Done-like button. Their rule
 files therefore keep the after-real-work `zeph_ask` — the "Entering REMOTE
 without a prompt hook" preamble in `src/templates.ts` — so the phone always
 has a button to tap that starts the loop. Agents with the hook drop that
-obligation while at the terminal.
+obligation while at the terminal — and their rule file carries only the
+NORMAL branch of the core (about a quarter of it), since it is read on every
+turn; the hook injects the REMOTE sections in full on the turn a phone
+message enters REMOTE, the way the Claude Code plugin's hooks do.
 
 `zeph cursor` has no remote-origin hook, so it never enters sticky REMOTE
 mode by itself. **Just ask for it** — one line, once per session:
@@ -664,6 +667,28 @@ others cannot: a turn with no tool calls, a turn with exactly one (a
 lone edit included — the gate wants two), and a turn whose calls were
 all reads. `/zeph-loud` still pushes on all of them.
 
+The Pi extension also pushes when pi is **waiting on you**: any blocking
+extension dialog — a bash guard's Run/Abort, an ask-user tool, a
+`ctx.ui.confirm` — that is still open 10 seconds after it appeared sends a
+`high` push ("pi asks: <project>", body = the dialog title or the guarded
+bash command). `high` gets through `quiet`; only `/zeph-mute` stops it.
+Answering inside the 10 seconds sends nothing. It is the pi twin of the
+Claude Code plugin's AskUserQuestion push, driven by pi's
+`ui_prompt_start` / `ui_prompt_end` events. Only dialogs that open while a
+turn is running count: a settings picker you open yourself between turns
+(`/caveman config`) never pushes.
+
+Two more end-of-turn cases differ from Claude Code:
+
+- **Push Signal markers** — pi's rules teach the same `<!-- zeph: skip|push|high -->`
+  markers, and the extension reads them from the final assistant message
+  (then strips them, since pi's terminal would otherwise print the comment).
+  `high` is how pi gets a "the turn ended with a question for you" push
+  through `quiet`.
+- **Errors and aborts** — a turn that ended on a provider error sends a
+  `high` "pi stopped: <project>" push with the error text instead of
+  "Task done"; a turn you aborted with Esc sends nothing.
+
 #### Quiet while away
 
 `quiet` silences routine pushes because you are watching the pane. When
@@ -789,7 +814,7 @@ try {
 | Copilot CLI | Session end hook + rules |
 | Cline | Rules file (`~/.cline/rules/zeph.md`) |
 | Aider | Conventions file + `read:` directive in `~/.aider.conf.yml` |
-| Pi | Extension (settle hook + remote detection) + rules — no MCP (pi has none; rules map zeph tools to the CLI) |
+| Pi | Extension (settle hook + waiting-on-you push + remote detection) + rules — no MCP (pi has none; rules map zeph tools to the CLI) |
 | OpenCode | MCP server + idle-notify plugin + rules |
 
 For remote-control via `zeph listener` the per-agent setup is the same

package/dist/core-sections.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Slice one `### ` section out of a generated rule core (zeph-core.generated.ts).
+ *
+ * The core is one string per audience, assembled upstream from
+ * plugin/docs/CORE_RULES.md. Two consumers need single sections of it:
+ * templates.ts, which builds the NORMAL-only rule file for agents whose
+ * prompt-submit hook can announce REMOTE, and remote-hook.ts, which injects
+ * the REMOTE sections on the turn that enters it — the twin of the plugin's
+ * zeph-remote.sh reading CORE_RULES.md on entry.
+ *
+ * Headings are matched by title prefix (`Sticky REMOTE mode`), not by the
+ * `(Rule N)` suffix: the extractor renumbers per audience, so the number is
+ * not stable across cores. A heading the core does not carry throws — every
+ * caller passes a literal, so the throw surfaces at import time in the tests
+ * rather than as a silently empty rule file.
+ */
+export declare const coreSection: (core: string, heading: string) => string;
+//# sourceMappingURL=core-sections.d.ts.map

package/dist/core-sections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-sections.d.ts","sourceRoot":"","sources":["../src/core-sections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MAO3D,CAAC"}

package/dist/core-sections.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coreSection = void 0;
+/**
+ * Slice one `### ` section out of a generated rule core (zeph-core.generated.ts).
+ *
+ * The core is one string per audience, assembled upstream from
+ * plugin/docs/CORE_RULES.md. Two consumers need single sections of it:
+ * templates.ts, which builds the NORMAL-only rule file for agents whose
+ * prompt-submit hook can announce REMOTE, and remote-hook.ts, which injects
+ * the REMOTE sections on the turn that enters it — the twin of the plugin's
+ * zeph-remote.sh reading CORE_RULES.md on entry.
+ *
+ * Headings are matched by title prefix (`Sticky REMOTE mode`), not by the
+ * `(Rule N)` suffix: the extractor renumbers per audience, so the number is
+ * not stable across cores. A heading the core does not carry throws — every
+ * caller passes a literal, so the throw surfaces at import time in the tests
+ * rather than as a silently empty rule file.
+ */
+const coreSection = (core, heading) => {
+    const sections = core.split(/^(?=### )/m).map((s) => s.trim());
+    const found = sections.filter((s) => s.startsWith(`### ${heading}`));
+    if (found.length !== 1) {
+        throw new Error(`core section "${heading}" ${found.length ? 'is ambiguous' : 'not found'} in the generated core`);
+    }
+    return found[0];
+};
+exports.coreSection = coreSection;

package/dist/remote-hook.d.ts

@@ -2,6 +2,7 @@
  *  NOT here — its hook ships with the plugin (hooks/zeph-remote.sh). */
 export declare const REMOTE_HOOK_AGENTS: readonly ["gemini", "codex", "pi"];
 export type RemoteHookAgent = (typeof REMOTE_HOOK_AGENTS)[number];
+export declare const remoteEntrySections: () => string;
 export declare const isRemoteHookAgent: (raw: string) => raw is RemoteHookAgent;
 /**
  * Core of the hook: match the stdin payload against the marker and return

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

@@ -1 +1 @@
-{"version":3,"file":"remote-hook.d.ts","sourceRoot":"","sources":["../src/remote-hook.ts"],"names":[],"mappings":"AA0CA;wEACwE;AACxE,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AACrE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAqClE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,GAAG,IAAI,eACE,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,eAAe,EACtB,OAAO,MAAM,EACb,MAAK,MAAM,CAAC,UAAwB,EACpC,MAAK,MAAM,MAAiB,KAC3B,MAAM,GAAG,IA0CX,CAAC"}
+{"version":3,"file":"remote-hook.d.ts","sourceRoot":"","sources":["../src/remote-hook.ts"],"names":[],"mappings":"AA4CA;wEACwE;AACxE,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AACrE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAkClE,eAAO,MAAM,mBAAmB,QAAO,MAGtB,CAAC;AAgBlB,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,GAAG,IAAI,eACE,CAAC;AAE1D;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,OAAO,eAAe,EACtB,OAAO,MAAM,EACb,MAAK,MAAM,CAAC,UAAwB,EACpC,MAAK,MAAM,MAAiB,KAC3B,MAAM,GAAG,IA2CX,CAAC"}

package/dist/remote-hook.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runRemoteHook = exports.isRemoteHookAgent = exports.REMOTE_HOOK_AGENTS = void 0;
+exports.runRemoteHook = exports.isRemoteHookAgent = exports.remoteEntrySections = exports.REMOTE_HOOK_AGENTS = void 0;
 /**
  * `zeph remote-hook <agent>` — prompt-submit hook handler for agents whose
  * hooks the cli installs directly: Gemini CLI (BeforeAgent), Codex CLI
@@ -33,6 +33,8 @@ exports.runRemoteHook = exports.isRemoteHookAgent = exports.REMOTE_HOOK_AGENTS =
  */
 const fs_1 = require("fs");
 const config_js_1 = require("./config.js");
+const core_sections_js_1 = require("./core-sections.js");
+const zeph_core_generated_js_1 = require("./zeph-core.generated.js");
 const gate_js_1 = require("./gate.js");
 /** Agents whose prompt-submit hooks this command serves. Claude Code is
  *  NOT here — its hook ships with the plugin (hooks/zeph-remote.sh). */
@@ -55,6 +57,21 @@ const FRESH_WINDOW_SEC = 900;
 const TWO_WAY_CONTEXT = `# System note (Zeph remote-origin detect)
 
 This user message arrived from the user's phone via Zeph agent chat (verified by the listener — exact text match). The user is driving this session remotely and is NOT at the terminal. Enter sticky REMOTE mode now (the "Sticky REMOTE mode" rule in your Zeph rules): end EVERY response with \`zeph_ask\` (buttons + free-text) until the user exits — an exit signal (done/stop/exit), or a prompt they type at the terminal, which this hook will tell you about. Plain-text questions are invisible to them.`;
+// The static rule file of these agents carries the NORMAL branch only
+// (templates.ts PROMPT_HOOK_CORE), so the turn that enters REMOTE is where the
+// contract has to arrive in full — the twin of plugin/hooks/zeph-remote.sh
+// reading CORE_RULES.md on entry. Read from the generated core rather than
+// restated here: a copy would be one more place for the rule to drift. The
+// four sections together cite only rules they carry (1–4, 7–9), so no
+// cross-reference dangles; remote-hook.test.ts checks that. Sent once per
+// entry: a later phone prompt on a session already in REMOTE gets the note
+// alone, since the contract is already in its context. Sliced on that turn
+// only — this command runs on every prompt submit, and the common path is a
+// silent no-op. Exported for the tests.
+const remoteEntrySections = () => ['When zeph_ask is MANDATORY', 'When zeph_ask is the DEFAULT', 'Sticky REMOTE mode', 'When to use AskUserQuestion vs zeph_ask']
+    .map((heading) => (0, core_sections_js_1.coreSection)(zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN, heading))
+    .join('\n\n');
+exports.remoteEntrySections = remoteEntrySections;
 const ONE_WAY_CONTEXT = `# System note (Zeph remote-origin detect)
 
 This user message arrived from the user's phone via Zeph agent chat (verified by the listener — exact text match), but no hook id is configured (neither \`ZEPH_HOOK_ID\` nor \`hookId\` in ~/.zeph/config.json), so two-way tools (zeph_ask/zeph_prompt/zeph_input) are unavailable. Make your final message self-contained — the completion push is the user's only feedback channel. If you have not already mentioned it this session, tell the user once that running \`npx @zeph-to/cli setup\` upgrades this into a two-way remote session (buttons + text replies from the phone).`;
@@ -105,8 +122,9 @@ const runRemoteHook = (agent, stdin, env = process.env, now = Date.now) => {
             return emit(ONE_WAY_CONTEXT);
         // Only a two-way session has a mode to stay in — without zeph_ask there is
         // nothing for a later turn to be reminded of, so no state is recorded.
+        const entering = !(0, gate_js_1.isRemoteActive)(cwd, now);
         (0, gate_js_1.touchRemoteActive)(cwd, now);
-        return emit(TWO_WAY_CONTEXT);
+        return emit(entering ? `${TWO_WAY_CONTEXT}\n\n${(0, exports.remoteEntrySections)()}` : TWO_WAY_CONTEXT);
     }
     if (origin === 'keyboard' && (0, gate_js_1.isRemoteActive)(cwd, now) && (0, config_js_1.resolveHookId)(env)) {
         (0, gate_js_1.clearRemoteActive)(cwd);

package/dist/templates.d.ts

@@ -1,10 +1,12 @@
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+export declare const PI_PROMPT_GRACE_MS = 10000;
 /** Cursor — written to ~/.cursor/rules/zeph.mdc (needs .mdc frontmatter). No prompt hook. */
 export declare const CURSOR_RULE: string;
 /** Windsurf — appended into ~/.codeium/windsurf/memories/global_rules.md. No prompt hook. */
 export declare const WINDSURF_RULE: string;
-/** Gemini CLI — appended into ~/.gemini/GEMINI.md. Has the prompt hook (GEMINI_HOOKS). */
+/** Gemini CLI — appended into ~/.gemini/GEMINI.md. Has the prompt hook (GEMINI_HOOKS), so NORMAL-only core. */
 export declare const GEMINI_RULE: string;
-/** Codex CLI — appended into ~/.codex/AGENTS.md. Has the prompt hook (CODEX_HOOKS). */
+/** Codex CLI — appended into ~/.codex/AGENTS.md. Has the prompt hook (CODEX_HOOKS), so NORMAL-only core. */
 export declare const CODEX_RULE: string;
 /** GitHub Copilot CLI — written to ~/.copilot/instructions/zeph.instructions.md. No prompt hook. */
 export declare const COPILOT_RULE: string;
@@ -12,7 +14,7 @@ export declare const COPILOT_RULE: string;
 export declare const CLINE_RULE: string;
 /** Aider — standalone conventions file via .aider.conf.yml `read:` (no Stop hook, no prompt hook). */
 export declare const AIDER_RULE: string;
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION), so NORMAL-only core. */
 export declare const PI_RULE: string;
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
 export declare const OPENCODE_RULE: string;

package/dist/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AA6KA,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,0FAA0F;AAC1F,eAAO,MAAM,WAAW,QAAyE,CAAC;AAElG,uFAAuF;AACvF,eAAO,MAAM,UAAU,QAAyE,CAAC;AAEjG,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,6GAA6G;AAC7G,eAAO,MAAM,OAAO,QAIlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAsDxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,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":"AAwGA,oGAAoG;AACpG,eAAO,MAAM,kBAAkB,QAAS,CAAC;AA8IzC,6FAA6F;AAC7F,eAAO,MAAM,WAAW,QAKtB,CAAC;AAEH,6FAA6F;AAC7F,eAAO,MAAM,aAAa,QAIxB,CAAC;AAEH,+GAA+G;AAC/G,eAAO,MAAM,WAAW,QAAoE,CAAC;AAE7F,4GAA4G;AAC5G,eAAO,MAAM,UAAU,QAAoE,CAAC;AAE5F,oGAAoG;AACpG,eAAO,MAAM,YAAY,QAIvB,CAAC;AAEH,gFAAgF;AAChF,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,sGAAsG;AACtG,eAAO,MAAM,UAAU,QAIrB,CAAC;AAEH,wJAAwJ;AACxJ,eAAO,MAAM,OAAO,QAKlB,CAAC;AAEH,2GAA2G;AAC3G,eAAO,MAAM,aAAa,QAIxB,CAAC;AAIH,eAAO,MAAM,YAAY,QAKd,CAAC;AAEZ,eAAO,MAAM,cAAc,QAOhB,CAAC;AAEZ,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;CAuBxB,CAAC;AAYF,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;CASvB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,OAAO,KAAG,OAUhD,CAAC;AAEF,eAAO,MAAM,aAAa,QASf,CAAC;AAQZ,2FAA2F;AAC3F,eAAO,MAAM,YAAY,QAgJxB,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,eAAe,QAwG3B,CAAC;AASF,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

@@ -23,11 +23,20 @@
 // ask itself — so for them the NORMAL branch must still send one after real
 // work, or the phone loop can never begin. That is REMOTE_ENTRY_NO_HOOK.
 //
+// The same axis decides how much of the core the static rule file carries.
+// That file is read on every turn, and a session is NORMAL nearly all of the
+// time, so for the three hook agents it carries the NORMAL branch only
+// (PROMPT_HOOK_CORE) — the REMOTE sections arrive from the hook on the turn
+// that enters REMOTE (remote-hook.ts remoteEntrySections), the way the
+// plugin's SessionStart / UserPromptSubmit pair does it for Claude Code. The
+// hook-less agents have no such turn, so their file keeps the whole 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.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = void 0;
+exports.removeManagedBlock = exports.upsertManagedBlock = exports.ZEPH_MARK_END = exports.ZEPH_MARK_START = exports.OPENCODE_PLUGIN = exports.PI_EXTENSION = exports.COPILOT_HOOKS = exports.isZephHookGroup = exports.CODEX_HOOKS = exports.GEMINI_HOOKS = exports.WINDSURF_HOOKS = exports.CURSOR_HOOKS = exports.OPENCODE_RULE = exports.PI_RULE = exports.AIDER_RULE = exports.CLINE_RULE = exports.COPILOT_RULE = exports.CODEX_RULE = exports.GEMINI_RULE = exports.WINDSURF_RULE = exports.CURSOR_RULE = exports.PI_PROMPT_GRACE_MS = void 0;
 const gate_js_1 = require("./gate.js");
+const core_sections_js_1 = require("./core-sections.js");
 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
@@ -73,6 +82,19 @@ const TURN_FACT_FLAGS = ` --${gate_js_1.TOOL_COUNT_FLAG} \${tools} --${gate_js_1
 // stderr is discarded; `|| true` keeps a broken install from ever blocking
 // a prompt.
 const remoteHookCmd = (agent) => `$(command -v zeph || echo "npx -y @zeph-to/cli") remote-hook ${agent} 2>/dev/null || true`;
+// One-off `high` push from the pi extension — a prompt left waiting (the twin
+// of the plugin's zeph-ask.sh) or a turn that died on an error. `high` gets
+// through the quiet dial, and plain `notify` (no --auto) means only a mute
+// stops it. Title and body arrive as env vars, never spliced into the string:
+// the body can carry the model's own bash command or a provider error.
+const highNotifyCmd = '$(command -v zeph || echo "npx -y @zeph-to/cli") notify'
+    + ' --title "$ZEPH_PUSH_TITLE" --body "$ZEPH_PUSH_BODY" --priority high 2>/dev/null || true';
+// The pi turn's Push Signal marker, as a JS template placeholder (single quotes:
+// `${marker}` must reach the artifact unexpanded). The artifact only ever
+// assigns it a word the marker regex captured, or "none".
+const PUSH_SIGNAL_FLAG = ' --marker ${marker}';
+/** Grace before the pi extension turns an unanswered prompt into a push. Exported for the tests. */
+exports.PI_PROMPT_GRACE_MS = 10_000;
 // ── Shared behavioral core ───────────────────────────────────────
 //
 // GENERATED from plugin/docs/CORE_RULES.md — see src/zeph-core.generated.ts
@@ -137,10 +159,55 @@ tool instead — same semantics:
   unreachable) is a Done-like outcome — treat it as NORMAL.
 - zeph_notify → \`zeph notify --title "…" --body "…" [--priority high]\`
 - AskUserQuestion → pi's own terminal prompt.`;
+// Push Signal preamble — pi only. The shared core has no Push Signal section:
+// Claude Code gets it from the plugin's SessionStart hook, per push dial. The
+// pi extension reads the same markers (PI_EXTENSION, message_end), so pi's
+// rules carry a dial-independent version here.
+const PI_PUSH_SIGNAL = `## Push Signal — steer the end-of-turn push
+
+When a turn ends, the zeph extension decides whether to push by tool volume
+and the user's push dial. Put ONE marker anywhere in your final response to
+override that for this turn. The extension removes it before the message is
+shown or kept:
+
+- \`<!-- zeph: high -->\` — push at high priority. The only marker that gets
+  through the quiet dial, so use it whenever the user must act: you ended the
+  turn with a question for them, or you are blocked on a decision only they
+  can make. Never on routine completions.
+- \`<!-- zeph: push -->\` — push a turn the heuristic would skip.
+- \`<!-- zeph: skip -->\` — no push for a turn not worth a ping.
+
+No marker → the heuristic: fewer than 2 tool calls, or only read-only ones,
+stays silent. Markers are lowercase and exact.`;
+// NORMAL-only core — agents WITH a prompt-submit hook (Gemini, Codex, Pi).
+// Mirrors plugin/hooks/zeph-setup.js `normal()`: the NORMAL branch owes no
+// `zeph_ask`, so it carries none of the REMOTE-scoped sections (MANDATORY /
+// DEFAULT / Sticky REMOTE / AskUserQuestion-vs) — about three quarters of the
+// core, paid on every turn of a session that is almost always NORMAL. What it
+// needs is the trigger: what flips the session, and what that turns on, stated
+// here rather than pointed at because a `zeph_ask` answer reporting
+// `zephState: "REMOTE"` flips it mid-turn with no hook to say so. The turn a
+// phone message arrives, remote-hook.ts injects the REMOTE sections in full.
+// Sections keep the numbers the core gave them (a render concern the extractor
+// settled per audience; the plugin's NORMAL branch has the same gaps).
+const REMOTE_STUB = `### What starts REMOTE
+
+The user sending a message from their phone starts sticky REMOTE — the prompt-submit hook says so on that turn and injects the contract in full. A \`zeph_ask\` result reporting \`zephState: "REMOTE"\` starts it mid-turn.
+
+From that response on: end EVERY response with \`zeph_ask\` (2–4 \`actions\` plus a Done-like \`fallback\`, \`timeout\` 300–600s), route button-friendly questions through it instead of \`AskUserQuestion\`, and never end on a plain-text question — until the user exits with a Done-like button, a free-text wrap-up you read as one (emit \`<!-- zeph: exit -->\` once), or a prompt they type at the terminal.`;
+const PROMPT_HOOK_CORE = [
+    `## NORMAL — the user is at the terminal
+
+Zeph can hand this session to the user's phone, but nobody has done that yet. **You owe no \`zeph_ask\`**: ask questions at the terminal or in prose, and let the end-of-turn push be the completion signal. A \`zeph_ask\` here blocks the turn until someone answers on a device or it times out.`,
+    (0, core_sections_js_1.coreSection)(zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN, 'Handling the response'),
+    REMOTE_STUB,
+    (0, core_sections_js_1.coreSection)(zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN, 'Persistence'),
+].join('\n\n');
 /** Assemble a full rule document from optional frontmatter + preambles + core. */
 const buildRule = (opts) => {
     const fm = opts.frontmatter ? `${opts.frontmatter}\n\n` : '';
     const tools = opts.toolAccess ? `${opts.toolAccess}\n\n` : '';
+    const signal = opts.pushSignal ? `${opts.pushSignal}\n\n` : '';
     const entry = opts.remoteEntry ? `${opts.remoteEntry}\n\n` : '';
     return `${fm}# Zeph — Remote-Control Rules
 
@@ -150,7 +217,7 @@ the user.
 
 ${opts.notify}
 
-${tools}${entry}${opts.core}
+${tools}${signal}${entry}${opts.core}
 `;
 };
 // ── Per-agent rule documents ─────────────────────────────────────
@@ -171,10 +238,10 @@ exports.WINDSURF_RULE = buildRule({
     remoteEntry: REMOTE_ENTRY_NO_HOOK,
     core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN,
 });
-/** Gemini CLI — appended into ~/.gemini/GEMINI.md. Has the prompt hook (GEMINI_HOOKS). */
-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. Has the prompt hook (CODEX_HOOKS). */
-exports.CODEX_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN });
+/** Gemini CLI — appended into ~/.gemini/GEMINI.md. Has the prompt hook (GEMINI_HOOKS), so NORMAL-only core. */
+exports.GEMINI_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: PROMPT_HOOK_CORE });
+/** Codex CLI — appended into ~/.codex/AGENTS.md. Has the prompt hook (CODEX_HOOKS), so NORMAL-only core. */
+exports.CODEX_RULE = buildRule({ notify: HOOK_DRIVEN_NOTIFY, core: PROMPT_HOOK_CORE });
 /** GitHub Copilot CLI — written to ~/.copilot/instructions/zeph.instructions.md. No prompt hook. */
 exports.COPILOT_RULE = buildRule({
     notify: HOOK_DRIVEN_NOTIFY,
@@ -193,11 +260,12 @@ exports.AIDER_RULE = buildRule({
     remoteEntry: REMOTE_ENTRY_NO_HOOK,
     core: zeph_core_generated_js_1.ZEPH_CORE_RULE_ONLY,
 });
-/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook (PI_EXTENSION). */
+/** Pi — managed block in ~/.pi/agent/AGENTS.md. Extension = Stop-equivalent + prompt hook + waiting-on-you push (PI_EXTENSION), so NORMAL-only core. */
 exports.PI_RULE = buildRule({
     notify: HOOK_DRIVEN_NOTIFY,
     toolAccess: PI_TOOL_ACCESS,
-    core: zeph_core_generated_js_1.ZEPH_CORE_HOOK_DRIVEN,
+    pushSignal: PI_PUSH_SIGNAL,
+    core: PROMPT_HOOK_CORE,
 });
 /** OpenCode — managed block in ~/.config/opencode/AGENTS.md. Stop hook via plugin, no prompt hook (v1). */
 exports.OPENCODE_RULE = buildRule({
@@ -320,20 +388,108 @@ const sh = (cmd: string, cwd: string, stdin?: string): Promise<string> =>
 // an unknown tool errs toward pushing rather than toward silence.
 const READ_ONLY = new Set(["read", "grep", "find", "ls"]);
 
+// How long a blocking prompt may stay open before it becomes a push. An answer
+// inside the window means the user is at the terminal, and a guard extension
+// can raise several prompts a turn — pushing each one at once would be noise.
+const PROMPT_GRACE_MS = ${exports.PI_PROMPT_GRACE_MS};
+
+// Push Signal markers — the pattern the Claude Code Stop hook reads
+// (plugin/hooks/zeph-stop.sh MARKER_RE). pi's markdown renders an HTML comment
+// as plain text, so message_end also strips it from what the user sees.
+const MARKER_RE = /<!--[ \\t]*zeph:[ \\t]*(skip|push|high)[ \\t]*-->/g;
+
+const projectOf = (cwd: string): string => cwd.split("/").pop() || cwd;
+
+// Fire-and-forget: never block pi on the notify network call.
+const pushHigh = (cwd: string, title: string, body: string): void => {
+  const env = {
+    ...process.env,
+    ZEPH_PUSH_TITLE: title,
+    ZEPH_PUSH_BODY: body.length > 200 ? body.slice(0, 199) + "…" : body,
+  };
+  const child = spawn("sh", ["-c", ${JSON.stringify(highNotifyCmd)}], { cwd, env, stdio: "ignore", detached: true });
+  child.on("error", () => {});
+  child.unref();
+};
+
 export default function (pi: ExtensionAPI) {
   // Turn facts for the push gate. One agent per process, so plain counters
   // suffice — no session keying.
   let tools = 0;
   let nonReadonly = 0;
+  // The tool call in flight. tool_execution_start fires before pi runs the
+  // tool_call handlers, so a guard's prompt always finds its own call here.
+  let running: { toolName: string; args: any } | undefined;
+  let promptTimer: ReturnType<typeof setTimeout> | undefined;
+  // A prompt only counts inside a turn. Outside one it is a dialog the user
+  // opened at the terminal themselves (/caveman config, a settings picker).
+  let agentRunning = false;
+  // This turn's Push Signal, and why its last assistant message stopped.
+  let marker = "none";
+  let stop: { reason: string; error?: string } | undefined;
 
+  pi.on("agent_start", () => {
+    agentRunning = true;
+  });
+  pi.on("message_end", (event) => {
+    const message = event.message;
+    if (message.role !== "assistant") return;
+    stop = { reason: message.stopReason, error: message.errorMessage };
+    let found = false;
+    const content = message.content.map((part) => {
+      if (part.type !== "text") return part;
+      const text = part.text.replace(MARKER_RE, (_match: string, word: string) => {
+        marker = word;
+        found = true;
+        return "";
+      });
+      return text === part.text ? part : { ...part, text: text.trimEnd() };
+    });
+    if (found) return { message: { ...message, content } };
+  });
+  pi.on("tool_execution_start", (event) => {
+    running = event;
+  });
   pi.on("tool_execution_end", (event) => {
+    running = undefined;
     tools += 1;
     if (!READ_ONLY.has(event.toolName)) nonReadonly += 1;
   });
+  // Waiting-on-you: pi fires ui_prompt_start for every blocking extension
+  // dialog (select/confirm/input/editor/custom — bash guards, ask-user tools).
+  // A custom dialog carries no title, so name the call that raised it instead.
+  pi.on("ui_prompt_start", (event, ctx) => {
+    clearTimeout(promptTimer);
+    if (!agentRunning) return;
+    const command = running?.toolName === "bash" ? running.args?.command : undefined;
+    const body = event.title
+      ?? (typeof command === "string" ? "$ " + command : undefined)
+      ?? (running ? running.toolName + " is waiting for your answer" : "Waiting for your input");
+    promptTimer = setTimeout(() => {
+      promptTimer = undefined;
+      pushHigh(ctx.cwd, "pi asks: " + projectOf(ctx.cwd), body);
+    }, PROMPT_GRACE_MS);
+    promptTimer.unref?.();
+  });
+  pi.on("ui_prompt_end", () => {
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+  });
   // Stop-equivalent: agent_settled fires once per user turn, after retries/compaction.
   // Fire-and-forget: never block pi's turn-end on the notify network call.
   pi.on("agent_settled", (_event, ctx) => {
-    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
+    agentRunning = false;
+    clearTimeout(promptTimer);
+    promptTimer = undefined;
+    // Esc (at the terminal, or a key sent from the phone): whoever stopped the
+    // turn is already looking at it.
+    if (stop?.reason === "aborted") return;
+    // A turn that died on a provider error is a blocker, not a completion.
+    if (stop?.reason === "error") {
+      pushHigh(ctx.cwd, "pi stopped: " + projectOf(ctx.cwd), stop.error || "The model request failed");
+      return;
+    }
+    const child = spawn("sh", ["-c", ${notifyCmdLiteral(TURN_FACT_FLAGS + PUSH_SIGNAL_FLAG)}], { cwd: ctx.cwd, stdio: "ignore", detached: true });
     child.on("error", () => {});
     child.unref();
   });
@@ -343,6 +499,8 @@ export default function (pi: ExtensionAPI) {
   pi.on("before_agent_start", async (event, ctx) => {
     tools = 0;
     nonReadonly = 0;
+    marker = "none";
+    stop = undefined;
     const out = await sh(${JSON.stringify(remoteHookCmd('pi'))}, ctx.cwd,
       JSON.stringify({ prompt: event.prompt, cwd: ctx.cwd }));
     try {

package/package.json

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