pi-better-goal 0.4.0 → 0.5.0

package/README.md

@@ -13,7 +13,8 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal; paused goals are never poked.
+- `escape` pauses the active goal, and it stays paused while you talk to the agent. Say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows `goal paused · say "go" or /goal resume`, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
+- Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
 - A progress-aware follow-up loop that holds after repeated identical outcomes.
@@ -30,6 +31,15 @@ metadata:
 
 Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit (or use `/workflow clear` to release it manually). Completing an active goal also releases ownership.
 
+A skill that is only an alias of a coordinator declares the target instead of a role:
+
+```yaml
+metadata:
+  workflow-alias-of: rush-issues
+```
+
+Invoking the alias (`/skill:resolve-issues`, or `/goal /skill:resolve-issues task`) records the target coordinator, with the target's registered path, as the workflow owner, so its task plan, continuation instructions, and plan tools behave exactly as if the target had been invoked. The target must be a registered `workflow-role: coordinator` skill; an unregistered target, a non-coordinator target, or a chain of aliases is refused with a notice.
+
 When `pi-better-plan` is installed, it defers its prompt, checklist, and `update_plan` tool to a skill-owned task plan. Skills without this metadata retain normal goal and plan behavior. The skill itself owns its planning format and worker policy; the harness does not enumerate skills or impose a shared workflow schema. The former `pi-better-plan-workflow: coordinator` metadata remains supported for installed skills.
 
 ## Install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
   "scripts": {
     "pretest": "node ../../scripts/sync-shared-log-utils.mjs",
     "prepack": "node ../../scripts/sync-shared-log-utils.mjs",
-    "test": "node --import tsx --test test/*.test.ts",
+    "test": "node --import tsx --import ../../scripts/isolate-registry.mjs --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
     "verify": "npm run typecheck && npm test"
   },

package/src/goal-state.ts

@@ -1,7 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { GoalCommandBinding } from "./command-binding.js";
 
-import { EXTENSION_NAME, type GoalSnapshot, type GoalStatus } from "./types.js";
+import { EXTENSION_NAME, type GoalPauseReason, type GoalSnapshot, type GoalStatus } from "./types.js";
 
 const LEGACY_GOAL_ENTRY_TYPE = "pi-codex-goal";
 const MAX_OBJECTIVE_CHARS = 8000;
@@ -17,6 +17,7 @@ interface GoalLike {
   objective: string;
   command?: unknown;
   status: GoalStatus;
+  pauseReason?: unknown;
   tokenBudget?: number | null;
   usage?: { tokensUsed?: number; activeSeconds?: number };
   createdAt?: number;
@@ -64,6 +65,10 @@ function isGoalStatus(value: unknown): value is GoalStatus {
   return value === "active" || value === "paused" || value === "budgetLimited" || value === "complete";
 }
 
+function isPauseReason(value: unknown): value is GoalPauseReason {
+  return value === "interrupt";
+}
+
 function isGoalLike(value: unknown): value is GoalLike {
   if (!value || typeof value !== "object") {
     return false;
@@ -119,6 +124,7 @@ function normalizeGoal(goal: GoalLike): GoalSnapshot {
     objective: goal.objective,
     ...(isCommandBinding(goal.command) ? { command: goal.command } : {}),
     status: goal.status,
+    ...(goal.status === "paused" && isPauseReason(goal.pauseReason) ? { pauseReason: goal.pauseReason } : {}),
     tokenBudget: typeof goal.tokenBudget === "number" ? goal.tokenBudget : null,
     usage: {
       tokensUsed: typeof goal.usage?.tokensUsed === "number" ? goal.usage.tokensUsed : 0,
@@ -209,7 +215,10 @@ export function goalWithStatus(
   goal: GoalSnapshot,
   status: GoalStatus,
   now = unixSeconds(),
+  pauseReason?: GoalPauseReason,
 ): GoalSnapshot {
+  const { pauseReason: _previousReason, ...rest } = goal;
+  goal = rest;
   const accruedActiveSeconds =
     goal.status === "active" && goal.activeStartedAt !== null
       ? Math.max(0, now - goal.activeStartedAt)
@@ -233,6 +242,7 @@ export function goalWithStatus(
   return {
     ...goal,
     status,
+    ...(status === "paused" && pauseReason ? { pauseReason } : {}),
     usage,
     updatedAt: now,
     activeStartedAt: null,

package/src/index.ts

@@ -45,6 +45,7 @@ import {
   EXTENSION_VERSION,
   type ActivitySnapshot,
   type BackgroundActivityProvider,
+  type BackgroundWorkItem,
   type GoalSnapshot,
 } from "./types.js";
 
@@ -63,6 +64,42 @@ const MAX_NO_PROGRESS_RETRIES = parseRetryLimit(
   DEFAULT_MAX_NO_PROGRESS_RETRIES,
 );
 
+/**
+ * Tools that block the foreground turn until the user answers. Background
+ * completions that arrive meanwhile queue behind the answer (Pi only drains
+ * steering after the whole tool batch, and callback batches are follow-ups
+ * that wait for the entire run), so the goal harvests them explicitly.
+ */
+/** Model-callable resume, active only while an escape-paused goal waits. */
+export const GOAL_RESUME_TOOL = "goal_resume";
+/** Hotkey that resumes any paused goal, like `/goal resume`. */
+export const GOAL_RESUME_SHORTCUT = "alt+g";
+
+/** When the agent may call `goal_resume`; shared by the tool description and the paused prompt. */
+const GOAL_RESUME_RULE =
+  "Call goal_resume only when the user's latest message clearly says to proceed (for example \"go\", \"continue\", \"ok do it\", \"approved, proceed\"), " +
+  "or answers a decision you explicitly asked for in your previous message with a choice that means proceed. Never call it for questions, \"why...\", \"what about...\", \"let me think\", or discussion.";
+
+/** True when the agent may resume this goal with `goal_resume`. */
+export function agentResumable(goal: GoalSnapshot | null): boolean {
+  return goal?.status === "paused" && goal.pauseReason === "interrupt";
+}
+
+/** Footer status for a paused goal, telling the user how to resume it. */
+export function pausedGoalStatus(goal: GoalSnapshot): string {
+  return agentResumable(goal) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
+}
+
+function pausedGoalPrompt(goal: GoalSnapshot): string {
+  return [
+    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
+    GOAL_RESUME_RULE,
+  ].join("\n");
+}
+
+const BLOCKING_QUESTION_TOOLS: ReadonlySet<string> = new Set(["ask_user_question"]);
+
 const GOAL_ACTIONS: readonly AutocompleteItem[] = [
   { value: "pause", label: "pause", description: "Pause the active goal" },
   { value: "resume", label: "resume", description: "Resume the paused goal" },
@@ -112,6 +149,46 @@ function wasTurnAborted(messages: readonly unknown[]): boolean {
   return false;
 }
 
+function activeItemsByKey(snapshot: ActivitySnapshot): Map<string, BackgroundWorkItem> {
+  const items = new Map<string, BackgroundWorkItem>();
+  for (const provider of snapshot.providers) {
+    for (const item of provider.items) {
+      if (item.active) items.set(`${provider.providerId}:${item.id}`, item);
+    }
+  }
+  return items;
+}
+
+/** Items that were active when a question started and are no longer active now. */
+export function finishedSinceQuestion(
+  activeAtStart: ReadonlyMap<string, BackgroundWorkItem>,
+  snapshot: ActivitySnapshot,
+): BackgroundWorkItem[] {
+  const stillActive = activeItemsByKey(snapshot);
+  const current = new Map<string, BackgroundWorkItem>();
+  for (const provider of snapshot.providers) {
+    for (const item of provider.items) current.set(`${provider.providerId}:${item.id}`, item);
+  }
+  const finished: BackgroundWorkItem[] = [];
+  for (const [key, started] of activeAtStart) {
+    if (stillActive.has(key)) continue;
+    finished.push(current.get(key) ?? { ...started, active: false, status: "unknown" });
+  }
+  return finished;
+}
+
+function questionHarvestPrompt(finished: readonly BackgroundWorkItem[]): string {
+  const rows = finished.map((item) => {
+    const label = item.label ? `${item.label} (${item.id})` : item.id;
+    return `- ${label}: ${item.status}`;
+  });
+  return [
+    `${finished.length} background item${finished.length === 1 ? "" : "s"} finished while you were waiting on the user's answer:`,
+    ...rows,
+    "Inspect and integrate these results now (for example with subagent_result or bg_task_status) before acting on the answer; their completion notices may still arrive later as a batch.",
+  ].join("\n");
+}
+
 function continuationPrompt(goal: GoalSnapshot, owner: ReturnType<typeof currentWorkflowOwner> = null): string {
   return [
     "Continue working toward the active thread goal.",
@@ -146,6 +223,11 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    ...(goal.status === "paused"
+      ? [agentResumable(goal)
+        ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
+        : "Resume: /goal resume or alt+g"]
+      : []),
   ].join("\n");
 }
 
@@ -188,12 +270,15 @@ export default function (pi: ExtensionAPI): void {
   let idleContinuationSignature = "";
   let refreshGoalWidget: ((force?: boolean) => void) | undefined;
   let lastAgentEvidence: ContinuationEvidence | null = null;
+  /** Background items active when each pending blocking question started, keyed by tool call id. */
+  const pendingQuestions = new Map<string, Map<string, BackgroundWorkItem>>();
 
   const getGoal = (ctx: ExtensionContext): GoalSnapshot | null => currentGoalSnapshot(ctx);
   const getWorkflow = (ctx: ExtensionContext) => currentWorkflowOwner(ctx.sessionManager.getBranch());
+  const registeredSkillPath = (name: string): string | undefined =>
+    pi.getCommands?.().find((item) => item.name === `skill:${name}` && item.source === "skill")?.sourceInfo.path;
   const workflowAvailable = (owner: NonNullable<ReturnType<typeof currentWorkflowOwner>>): boolean => {
-    const command = pi.getCommands?.().find((item) => item.name === `skill:${owner.name}` && item.source === "skill");
-    if (command?.sourceInfo.path !== owner.path) return false;
+    if (registeredSkillPath(owner.name) !== owner.path) return false;
     try {
       return workflowOwnerFromSkill(owner.name, owner.path)?.planOwner === owner.planOwner;
     } catch {
@@ -252,6 +337,8 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(goal);
+    applyStatus(ctx);
     // Force a full redraw when the dock height changes (absent ↔ visible clock).
     refreshGoalWidget?.(!wasVisible || !isGoalClockVisible(goal));
   };
@@ -265,16 +352,57 @@ export default function (pi: ExtensionAPI): void {
     backgroundDrainTracker = null;
     clearIdleContinuation();
     syncPollingState();
+    syncResumeTool(null);
+    applyStatus(ctx);
     refreshGoalWidget?.(wasVisible);
   };
 
+  /**
+   * An interrupt (escape, or anything else that aborts the running turn) pauses
+   * the goal. It stays paused while the user talks: messages are ordinary
+   * conversation. It resumes through `/goal resume`, the hotkey, or the agent's
+   * `goal_resume` once the user clearly says to proceed.
+   */
   const pauseGoalOnInterrupt = (ctx: ExtensionContext): void => {
     const goal = getGoal(ctx);
     if (!isPokeable(goal)) {
       return;
     }
-    setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
-    notifyGoal(ctx, "Goal paused (interrupted).");
+    setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
+    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
+  };
+
+  /** Why a paused goal cannot become active again, or null when it can. */
+  const resumeBlocker = (goal: GoalSnapshot): string | null => {
+    if (!goal.command && skillCommandName(goal.objective)) {
+      return "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.";
+    }
+    if (goal.command && !commandAvailable(pi, goal.command)) {
+      return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
+    }
+    return null;
+  };
+
+  /**
+   * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
+   * reactivate the paused goal and queue its continuation.
+   */
+  const resumeGoal = (
+    ctx: ExtensionContext,
+    source: GoalEntrySource,
+  ): { ok: true; goal: GoalSnapshot } | { ok: false; message: string } => {
+    const current = getGoal(ctx);
+    if (!current || current.status !== "paused") {
+      return { ok: false, message: "Only paused goals can be resumed." };
+    }
+    const blocker = resumeBlocker(current);
+    if (blocker) {
+      return { ok: false, message: blocker };
+    }
+    const goal = goalWithStatus(current, "active");
+    setGoal(goal, ctx, source);
+    queueGoalContinuation(goal, ctx);
+    return { ok: true, goal };
   };
 
   const boundCommandReady = (goal: GoalSnapshot, ctx: ExtensionContext): boolean => {
@@ -392,7 +520,7 @@ export default function (pi: ExtensionAPI): void {
     }
     const goal = createGoalSnapshot(objective.trim(), tokenBudget, undefined, command ?? undefined);
     const owner = command?.source === "skill"
-      ? workflowOwnerFromSkill(command.name.slice("skill:".length), command.path)
+      ? workflowOwnerFromSkill(command.name.slice("skill:".length), command.path, registeredSkillPath)
       : null;
     if (getWorkflow(ctx)) recordWorkflow(null);
     setGoal(goal, ctx, source);
@@ -434,30 +562,62 @@ export default function (pi: ExtensionAPI): void {
       clearIdleContinuation();
     }
 
-    if (ctx.hasUI) {
-      const goal = getGoal(ctx);
-      const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
-      const goalStall = observeGoalStall(goal, continuation, {
-        foregroundRunning,
-        backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
-      });
-      const status = snapshot.backgroundRunning
-        ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
-        : continuation?.blocked
-          ? "waiting: no progress"
-          : goalStall?.state === "stalled"
-            ? "goal stalled"
-          : undefined;
-      try {
-        ctx.ui.setStatus(EXTENSION_NAME, status);
-      } catch {
-        // UI status is best-effort only.
-      }
-    }
+    applyStatus(ctx);
 
     return snapshot;
   };
 
+  /** Footer status from the goal state and the latest activity snapshot. */
+  const statusText = (ctx: ExtensionContext, snapshot: ActivitySnapshot | null): string | undefined => {
+    const goal = getGoal(ctx);
+    let waitingOnAnswer = 0;
+    if (snapshot) {
+      for (const activeAtStart of pendingQuestions.values()) {
+        waitingOnAnswer += finishedSinceQuestion(activeAtStart, snapshot).length;
+      }
+    }
+    if (waitingOnAnswer > 0) return `${waitingOnAnswer} background done; waiting on your answer`;
+    const background = snapshot?.backgroundRunning
+      ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
+      : undefined;
+    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal)} · ${background}` : pausedGoalStatus(goal);
+    if (background) return background;
+    const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
+    if (continuation?.blocked) return "waiting: no progress";
+    const goalStall = observeGoalStall(goal, continuation, {
+      foregroundRunning,
+      backgroundRunning: snapshot?.backgroundRunning ?? false,
+    });
+    return goalStall?.state === "stalled" ? "goal stalled" : undefined;
+  };
+
+  function applyStatus(ctx: ExtensionContext): void {
+    if (!ctx.hasUI) return;
+    try {
+      ctx.ui.setStatus(EXTENSION_NAME, statusText(ctx, latestSnapshot));
+    } catch {
+      // UI status is best-effort only.
+    }
+  }
+
+  /**
+   * `goal_resume` is in the model's tool list only while an escape-paused goal
+   * waits. Pi activates newly registered tools by default, so this also removes
+   * it at session start. Only this one tool is toggled; other extensions' tool
+   * choices are left as they are.
+   */
+  function syncResumeTool(goal: GoalSnapshot | null): void {
+    if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+    try {
+      const active = pi.getActiveTools();
+      const wanted = agentResumable(goal);
+      if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
+      pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
+    } catch {
+      // Tool activation is unavailable before Pi binds the session; the tool also refuses on its own.
+    }
+  }
+
   const collectIfPossible = (): void => {
     const ctx = currentCtx;
     if (!ctx) {
@@ -600,21 +760,11 @@ export default function (pi: ExtensionAPI): void {
       }
 
       if (trimmed === "resume") {
-        if (!current || current.status !== "paused") {
-          notifyGoal(ctx, "Only paused goals can be resumed.", "warning");
-          return;
-        }
-        if (!current.command && skillCommandName(current.objective)) {
-          notifyGoal(ctx, "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.", "error");
-          return;
-        }
-        if (current.command && !commandAvailable(pi, current.command)) {
-          notifyGoal(ctx, `Cannot resume: /${current.command.name} is no longer registered at its original source.`, "error");
+        const result = resumeGoal(ctx, "command");
+        if (!result.ok) {
+          notifyGoal(ctx, result.message, current?.status === "paused" ? "error" : "warning");
           return;
         }
-        const goal = goalWithStatus(current, "active");
-        setGoal(goal, ctx, "command");
-        queueGoalContinuation(goal, ctx);
         notifyGoal(ctx, "Goal resumed.");
         return;
       }
@@ -717,6 +867,44 @@ export default function (pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: GOAL_RESUME_TOOL,
+    label: "Resume Goal",
+    description:
+      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+    parameters: Type.Object({
+      reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const reason = (params as { reason?: string }).reason;
+      const current = getGoal(ctx);
+      if (!agentResumable(current)) {
+        const text = current?.status === "paused"
+          ? "This goal was paused with /goal pause or by the runtime. Only the user can resume it, with /goal resume."
+          : "No goal is paused, so there is nothing to resume.";
+        return { content: [{ type: "text", text }], details: { ok: false, goal: current } };
+      }
+      const result = resumeGoal(ctx, "tool");
+      if (!result.ok) {
+        return { content: [{ type: "text", text: `Goal stays paused. ${result.message}` }], details: { ok: false, goal: getGoal(ctx) } };
+      }
+      return {
+        content: [{ type: "text", text: "Goal resumed. Its continuation runs after this turn." }],
+        details: { ok: true, goal: result.goal, ...(reason ? { reason } : {}) },
+      };
+    },
+  });
+
+  pi.registerShortcut?.(GOAL_RESUME_SHORTCUT, {
+    description: "Resume the paused goal",
+    handler: (ctx) => {
+      currentCtx = ctx;
+      const result = resumeGoal(ctx, "command");
+      notifyGoal(ctx, result.ok ? "Goal resumed." : result.message, result.ok ? "info" : "warning");
+    },
+  });
+
   pi.registerCommand("better-activity", {
     description: "Show foreground/background activity known to pi-better-goal",
     handler: async (_args, ctx) => {
@@ -777,6 +965,7 @@ export default function (pi: ExtensionAPI): void {
       notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
     }
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
+    syncResumeTool(getGoal(ctx));
     installGoalWidget(ctx);
     latestSnapshot = await publishSnapshot(ctx);
     syncPollingState();
@@ -794,7 +983,7 @@ export default function (pi: ExtensionAPI): void {
       const command = pi.getCommands?.().find((item) => item.name === `skill:${skillName}` && item.source === "skill");
       if (command) {
         try {
-          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path);
+          const owner = workflowOwnerFromSkill(skillName, command.sourceInfo.path, registeredSkillPath);
           if (owner) recordWorkflow(owner);
         } catch (error) {
           notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
@@ -802,6 +991,8 @@ export default function (pi: ExtensionAPI): void {
         }
       }
     }
+    // A paused goal stays paused while the user talks: the message is ordinary
+    // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
     if (goal?.status === "active") {
       resetContinuationState(goal);
@@ -813,10 +1004,15 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
+    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
     if (!isPokeable(goal) && !owner) {
-      return;
+      return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
 
+    const questionInstruction = snapshot.backgroundRunning
+      ? " A blocking user question (ask_user_question) holds this whole turn until the user answers, and background completions wait behind it. Harvest finished background results before asking, and ask only when the answer is needed to proceed."
+      : "";
+
     if (owner) {
       if (!workflowAvailable(owner)) {
         if (isPokeable(goal)) setGoal(goalWithStatus(goal, "paused"), ctx, "runtime");
@@ -831,8 +1027,13 @@ export default function (pi: ExtensionAPI): void {
         return { systemPrompt: `${event.systemPrompt}\n\nWorkflow ${owner.name} is unavailable. Stop work and ask the user to restore or reinvoke the skill.` };
       }
       return {
-        systemPrompt: `${event.systemPrompt}\n\nActive workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
-          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : ""),
+        systemPrompt: `${event.systemPrompt}\n\n` +
+          (pausedInstruction
+            ? `${pausedInstruction}\nWhile the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n`
+            : "") +
+          `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
+          (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
+          (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
       };
     }
 
@@ -843,7 +1044,7 @@ export default function (pi: ExtensionAPI): void {
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}`,
+        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}`,
     };
   });
 
@@ -875,6 +1076,32 @@ export default function (pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("tool_execution_start", async (event, ctx) => {
+    if (!BLOCKING_QUESTION_TOOLS.has(event.toolName)) return;
+    currentCtx = ctx;
+    const snapshot = await publishSnapshot(ctx);
+    const active = activeItemsByKey(snapshot);
+    if (active.size > 0) pendingQuestions.set(event.toolCallId, active);
+  });
+
+  pi.on("tool_execution_end", async (event, ctx) => {
+    const activeAtStart = pendingQuestions.get(event.toolCallId);
+    if (!activeAtStart) return;
+    pendingQuestions.delete(event.toolCallId);
+    currentCtx = ctx;
+    const snapshot = await publishSnapshot(ctx);
+    const finished = finishedSinceQuestion(activeAtStart, snapshot);
+    if (finished.length === 0) return;
+    // Steering is drained right after this tool batch, so the model sees the
+    // finished work together with the user's answer instead of after the run.
+    pi.sendMessage({
+      customType: EXTENSION_NAME,
+      content: questionHarvestPrompt(finished),
+      display: false,
+      details: { kind: "question-harvest", toolCallId: event.toolCallId, finished: finished.map((item) => ({ id: item.id, status: item.status })) },
+    }, { deliverAs: "steer", triggerTurn: true });
+  });
+
   pi.on("agent_settled", async (_event, ctx) => {
     currentCtx = ctx;
     foregroundRunning = false;
@@ -917,6 +1144,7 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_shutdown", async (_event, ctx) => {
     stopPolling();
     foregroundRunning = false;
+    pendingQuestions.clear();
     clearIdleContinuation();
     currentCtx = undefined;
     latestSnapshot = null;

package/src/types.ts

@@ -65,6 +65,16 @@ export interface ActivitySnapshot {
 
 export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
 
+/**
+ * Why a paused goal is paused. `interrupt` marks a pause from escape (or any
+ * other abort of the running turn). Every pause is sticky: user messages never
+ * resume a goal on their own. An `interrupt` pause may be resumed by the agent
+ * with `goal_resume` when the user clearly says to proceed. A paused goal
+ * without a reason (`/goal pause`, an unavailable command or workflow) resumes
+ * only through `/goal resume` or the resume hotkey.
+ */
+export type GoalPauseReason = "interrupt";
+
 export interface GoalUsage {
   tokensUsed: number;
   activeSeconds: number;
@@ -75,6 +85,8 @@ export interface GoalSnapshot {
   objective: string;
   command?: GoalCommandBinding;
   status: GoalStatus;
+  /** Present only while `status` is "paused". */
+  pauseReason?: GoalPauseReason;
   tokenBudget: number | null;
   usage: GoalUsage;
   createdAt: number;

package/src/workflow.ts

@@ -16,7 +16,12 @@ interface SessionEntryLike {
   data?: unknown;
 }
 
-export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwner | null {
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** Resolves a registered skill's name to its SKILL.md path, or undefined when it is not registered. */
+export type SkillPathResolver = (name: string) => string | undefined;
+
+function skillMetadata(path: string): Record<string, unknown> | null {
   const source = readFileSync(path, "utf8");
   const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
   if (!match) return null;
@@ -24,9 +29,34 @@ export function workflowOwnerFromSkill(name: string, path: string): WorkflowOwne
   if (!frontmatter || typeof frontmatter !== "object") return null;
   const metadata = (frontmatter as { metadata?: unknown }).metadata;
   if (!metadata || typeof metadata !== "object") return null;
-  const fields = metadata as Record<string, unknown>;
+  return metadata as Record<string, unknown>;
+}
+
+/**
+ * Reads a skill's workflow declaration. A coordinator declares `workflow-role: coordinator`.
+ * An alias declares `workflow-alias-of: <skill>` and resolves, through the registered skill
+ * commands, to that coordinator: the recorded owner is the target (its name and path), so
+ * invoking the alias is indistinguishable from invoking the coordinator. Aliases do not chain.
+ */
+export function workflowOwnerFromSkill(name: string, path: string, resolveSkillPath?: SkillPathResolver): WorkflowOwner | null {
+  const fields = skillMetadata(path);
+  if (!fields) return null;
   const role = fields["workflow-role"];
   const legacyRole = fields["pi-better-plan-workflow"];
+  const aliasOf = fields["workflow-alias-of"];
+  if (aliasOf !== undefined) {
+    if (typeof aliasOf !== "string" || !SKILL_NAME.test(aliasOf) || aliasOf === name ||
+        role !== undefined || legacyRole !== undefined) {
+      throw new Error(`Invalid workflow metadata in ${path}. Expected workflow-alias-of: <coordinator skill name> without workflow-role.`);
+    }
+    const targetPath = resolveSkillPath?.(aliasOf);
+    if (!targetPath) throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is not a registered skill.`);
+    const target = workflowOwnerFromSkill(aliasOf, targetPath, () => {
+      throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is itself an alias; aliases do not chain.`);
+    });
+    if (!target) throw new Error(`Workflow alias ${name} targets ${aliasOf}, which is not a workflow coordinator.`);
+    return target;
+  }
   if (role === undefined && legacyRole === undefined) {
     if (fields["pi-better-workflow-role"] !== undefined || fields["pi-better-plan-owner"] !== undefined) {
       throw new Error(`Outdated workflow metadata in ${path}. Use workflow-role: coordinator.`);