@trevonistrevon/pi-loop 0.6.2 → 0.6.4

package/src/tools/loop-tools.ts

@@ -2,8 +2,10 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { formatTrigger } from "../loop-format.js";
 import { parseInterval } from "../loop-parse.js";
-import type { LoopEntry, Trigger } from "../types.js";
-import { textResult } from "./tool-result.js";
+import type { LoopEntry, Trigger, WorkflowDefinition } from "../types.js";
+import { renderToolCall, renderToolResult, toolArg } from "../ui/tool-renderer.js";
+import { validateWorkflowDefinition } from "../workflow-reducer.js";
+import { displayRows, textResult } from "./tool-result.js";
 
 interface LoopStoreLike {
   list(): LoopEntry[];
@@ -14,9 +16,18 @@ interface LoopStoreLike {
     taskBacklog?: boolean;
     readOnly?: boolean;
     maxFires?: number;
+    dynamic?: Partial<NonNullable<LoopEntry["dynamic"]>>;
+    workflow?: WorkflowDefinition;
   }): LoopEntry;
   pause(id: string): LoopEntry | undefined;
   updateDynamic(id: string, fields: { prompt?: string; dynamic: Partial<NonNullable<LoopEntry["dynamic"]>> }): LoopEntry | undefined;
+  transitionWorkflow(id: string, input: { outcome: string; evidence?: string; activeTaskId?: string }): {
+    entry?: LoopEntry;
+    applied: boolean;
+    error?: string;
+    terminal?: "completed" | "paused";
+  };
+  setWorkflowActiveTask(id: string, taskId?: string): LoopEntry | undefined;
   getDeletionTombstone(id: string): { reason: string; pendingCount?: number } | undefined;
   delete(id: string): boolean;
 }
@@ -48,6 +59,9 @@ export interface LoopToolsOptions {
   updateWidget: () => void;
   maybeBootstrapTaskLoop: (entry: LoopEntry) => Promise<boolean>;
   isTaskSystemReady: () => boolean;
+  onDynamicLoopActivated?: (entry: LoopEntry) => void;
+  createWorkflowTask?: (entry: LoopEntry) => Promise<string | undefined>;
+  completeWorkflowTask?: (taskId: string) => Promise<boolean>;
 }
 
 function validateTrigger(trigger: Trigger): string | null {
@@ -111,6 +125,57 @@ function resolveNextWakeAt(nextInterval?: string): { nextWakeAt?: number; error?
   return { nextWakeAt: Date.now() + parsedDelayMs };
 }
 
+function parseWorkflowDefinition(input: string): { definition?: WorkflowDefinition; error?: string } {
+  try {
+    const parsed = JSON.parse(input) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { error: "Workflow definition must be a JSON object" };
+    }
+    const definition = parsed as WorkflowDefinition;
+    const validationError = validateWorkflowDefinition(definition);
+    return validationError ? { error: validationError } : { definition };
+  } catch {
+    return { error: "Workflow definition must be valid JSON" };
+  }
+}
+
+const WORKFLOW_DEFINITION_EXAMPLE =
+  '{"version":1,"initialState":"investigate","states":{"investigate":{"prompt":"Investigate the issue.","on":{"found":"done"}},"done":{"prompt":"Report completion.","terminal":"completed"}}}';
+
+function formatWorkflowDefinitionError(error: string | undefined): string {
+  return `Workflow definition rejected: ${error ?? "unknown validation error"}\n` +
+    "Required fields: version: 1, initialState, and states.\n" +
+    `Example definition:\n${WORKFLOW_DEFINITION_EXAMPLE}\n` +
+    "Next: correct the JSON and call WorkflowCreate again.";
+}
+
+function formatWorkflowSummary(entry: LoopEntry, heading: string): string {
+  const workflow = entry.workflow!;
+  const state = workflow.definition.states[workflow.currentState];
+  const outcomes = Object.keys(state?.on ?? {});
+  let message = `${heading}\nGoal: ${entry.prompt}\nCurrent state: ${workflow.currentState}`;
+  if (state?.prompt) message += `\nInstruction: ${state.prompt}`;
+  if (workflow.activeTaskId) {
+    message += `\nActive task: #${workflow.activeTaskId}`;
+  } else if (state?.task) {
+    message += "\nTask: no task was created for this state";
+  } else {
+    message += "\nTask: none configured for this state";
+  }
+
+  if (state?.terminal) {
+    message += `\nTerminal: ${state.terminal}`;
+    return message;
+  }
+  if (outcomes.length === 0) {
+    return `${message}\nNeeds attention: this state has no declared outcomes, so it cannot advance.`;
+  }
+
+  message += `\nChoose outcome: ${outcomes.join(", ")}`;
+  message += `\nNext: WorkflowTransition({ id: "${entry.id}", outcome: "${outcomes[0]}", evidence: "..." })`;
+  return message;
+}
+
 function formatDynamicUpdateResult(id: string, iteration: number | undefined, nextWakeAt: number | undefined): string {
   const mode = nextWakeAt === undefined
     ? "Next wake: when idle"
@@ -178,11 +243,16 @@ export function registerLoopTools(options: LoopToolsOptions): void {
     updateWidget,
     maybeBootstrapTaskLoop,
     isTaskSystemReady,
+    onDynamicLoopActivated,
+    createWorkflowTask,
+    completeWorkflowTask,
   } = options;
 
   pi.registerTool({
     name: "LoopCreate",
     label: "LoopCreate",
+    renderCall: renderToolCall("Loop", (args) => `create · ${String(toolArg(args, "prompt") ?? "scheduled work").slice(0, 56)}`),
+    renderResult: renderToolResult,
     description: `Create a scheduled repeating task (loop) that runs a prompt on a timer or when an event fires.
 
 Use this tool whenever the user asks to:
@@ -214,7 +284,11 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
 - **autoTask**: when pi-tasks is loaded or native task fallback is active, auto-create a task on each fire
 - **taskBacklog**: mark this as a task-backlog worker loop so it auto-deletes when pending tasks reach zero
 - **readOnly**: restrict the agent to read-only tools when this loop fires (default: false)
-- **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops`,
+- **maxFires**: auto-stop after N fires — prevents infinite token burn on polling loops
+
+## Loop Lifecycle
+
+Recurring loops persist across fires. A completed iteration, unchanged result, or temporarily empty check is not a reason to delete the loop. Delete only when the user explicitly cancels it or its stated stop condition is satisfied. Dynamic loops must be advanced with LoopUpdate, not LoopDelete.`,
     promptGuidelines: [
       "Use LoopCreate when the user asks for a repeating task, periodic check, scheduled reminder, or 'every X' — never use raw Bash for/sleep/while.",
       "## Choosing trigger type",
@@ -226,14 +300,14 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       "Default to 5m unless the user specifies differently. Use shorter intervals only when time-sensitive.",
       "## maxFires — prevent infinite token burn",
       "Always set maxFires on polling loops so they don't run forever. For task-continuation loops, use maxFires: 20-50.",
-      "When a loop fires and finds nothing to do, call LoopDelete on its own ID to stop it — don't keep polling.",
+      "Recurring loops are persistent controllers. Do not call LoopDelete after a normal fire, an unchanged check, or one completed iteration; only delete when the user explicitly asks to cancel or the loop's stated stop condition is satisfied.",
       "## readOnly mode",
       "Set readOnly: true for loops that only observe and report (checks, status polls). This prevents unintended changes.",
       "## Task-driven workflows",
       "Do not rely on a past 'tasks:created' event to replay. If tasks already exist, bootstrap the first pass in the current turn or use a hybrid/event loop that can catch future task creation and a cron safety-net.",
       "Use autoTask only when you want the loop itself to create a task on each fire. For processing an existing task backlog, leave autoTask off and have the loop run TaskList to pick the next pending task.",
       "Set taskBacklog: true for backlog worker loops that process the existing pending queue. Backlog worker loops bootstrap against existing pending tasks and auto-delete when the queue reaches zero.",
-      "When no tasks are pending, the loop should stop itself or skip the wake entirely — no tokens burned on empty polls.",
+      "For taskBacklog loops, do not instruct the agent to delete the loop; pi-loop auto-deletes it when the pending count reaches zero.",
       "After creating a loop, tell the user the loop ID so they can cancel it with LoopDelete.",
     ],
     parameters: Type.Object({
@@ -271,7 +345,15 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
       }
 
       const validationError = validateTrigger(trigger);
-      if (validationError) return Promise.resolve(textResult(validationError));
+      if (validationError) {
+        return Promise.resolve(textResult(validationError, {
+          kind: "loop",
+          action: "create",
+          tone: "error",
+          summary: "Loop was not created",
+          expanded: [validationError],
+        }));
+      }
 
       const entry = getStore().create(trigger, prompt, {
         recurring: recurring ?? (inferred !== "event"),
@@ -312,7 +394,224 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
         (entry.taskBacklog ? "Backlog worker: enabled\n" : "") +
         (bootstrapped ? "Backlog: initial wake queued for existing pending tasks\n" : "") +
         (isTaskSystemReady() ? "" : "Task system: not ready yet — autoTask may not fire until native fallback or pi-tasks becomes available\n") +
-        `ID: ${entry.id} (use LoopDelete to cancel)`
+        `ID: ${entry.id} (persists until explicitly canceled or a configured stop condition is met)`,
+        {
+          kind: "loop",
+          action: "create",
+          tone: "success",
+          summary: `Loop #${entry.id} active · ${triggerDesc}`,
+          expanded: [
+            `Goal: ${entry.prompt}`,
+            `Trigger: ${triggerDesc}`,
+            entry.autoTask ? "Auto-task: enabled" : "Auto-task: off",
+          ],
+        },
+      ));
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowCreate",
+    label: "WorkflowCreate",
+    renderCall: renderToolCall("Workflow", (args) => `create · ${String(toolArg(args, "goal") ?? "workflow").slice(0, 56)}`),
+    renderResult: renderToolResult,
+    description: `Create an opt-in task-driven workflow loop from a JSON state definition.
+
+Use this when work has named phases and explicit outcomes, such as investigate → fix → validate. Use LoopCreate for ordinary scheduled/event work and TaskCreate for a normal flat backlog.
+
+The definition requires version: 1, initialState, and states. Each state has a prompt, optional on outcome-to-state map, optional maxAttempts, and an optional terminal value of completed or paused.`,
+    promptGuidelines: [
+      "Use WorkflowCreate only for explicit multi-phase work with stable named outcomes; ordinary reminders, polling, and task backlogs should remain loops or tasks.",
+      "Pass `definition` as valid JSON. Give each non-terminal state a concise prompt and explicit outcome names, for example `root_cause_found` or `tests_pass`.",
+      "After each workflow wake, call WorkflowTransition with the workflow `id` and one declared `outcome`; include concise `evidence` whenever a branch is chosen.",
+    ],
+    parameters: Type.Object({
+      goal: Type.String({ description: "Overall workflow goal" }),
+      definition: Type.String({ description: "Workflow JSON: version, initialState, and named states" }),
+      maxFires: Type.Optional(Type.Number({ description: "Maximum workflow wakes before automatic expiry (default: 30)", default: 30 })),
+    }),
+    async execute(_toolCallId, params) {
+      const parsed = parseWorkflowDefinition(params.definition);
+      if (!parsed.definition) {
+        const message = formatWorkflowDefinitionError(parsed.error);
+        return textResult(message, {
+          kind: "workflow",
+          action: "create",
+          tone: "error",
+          summary: "Workflow definition rejected",
+          expanded: [parsed.error ?? "unknown validation error", "Expand the tool result for a valid definition skeleton."],
+        });
+      }
+
+      let entry = getStore().create({ type: "dynamic" }, params.goal, {
+        recurring: true,
+        maxFires: params.maxFires ?? 30,
+        dynamic: { goal: params.goal, state: parsed.definition.initialState, iteration: 0 },
+        workflow: parsed.definition,
+      });
+      const taskId = await createWorkflowTask?.(entry);
+      if (taskId) entry = getStore().setWorkflowActiveTask(entry.id, taskId) ?? entry;
+      getTriggerSystem().add(entry);
+      updateWidget();
+      onDynamicLoopActivated?.(entry);
+      return textResult(
+        `${formatWorkflowSummary(entry, `Workflow #${entry.id} created — ${entry.status}`)}\n` +
+        "Wake: the state instruction will be delivered when the agent becomes idle.",
+        {
+          kind: "workflow",
+          action: "create",
+          tone: "success",
+          summary: `Workflow #${entry.id} active · ${parsed.definition.initialState}${taskId ? ` · task #${taskId}` : ""}`,
+          expanded: [
+            `Goal: ${entry.prompt}`,
+            `State: ${parsed.definition.initialState}`,
+            `Outcome: ${Object.keys(parsed.definition.states[parsed.definition.initialState]?.on ?? {}).join(", ") || "none"}`,
+            "Wake: delivered when the agent becomes idle",
+          ],
+        },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowTransition",
+    label: "WorkflowTransition",
+    renderCall: renderToolCall("Workflow", (args) => `transition · #${String(toolArg(args, "id") ?? "?")} → ${String(toolArg(args, "outcome") ?? "?")}`),
+    renderResult: renderToolResult,
+    description: `Advance an opt-in workflow using one declared outcome.
+
+Use exactly once after completing the current workflow state. The outcome must be declared in the current state's on map. Include evidence for the branch decision. This tool validates the transition, records it, and queues the next state; it completes or pauses terminal workflows automatically.`,
+    promptGuidelines: [
+      "WorkflowTransition uses `id`, not `loopId`.",
+      "Use an exact outcome name declared by the current state. Do not invent an outcome; inspect the wake message or WorkflowList first.",
+      "Include `evidence` that justifies the transition, especially for completion, regression, or blocked outcomes.",
+    ],
+    parameters: Type.Object({
+      id: Type.String({ description: "Workflow loop ID" }),
+      outcome: Type.String({ description: "Declared outcome for the current workflow state" }),
+      evidence: Type.Optional(Type.String({ description: "Concise evidence supporting this transition" })),
+      activeTaskId: Type.Optional(Type.String({ description: "Optional task ID now active in the destination state" })),
+    }),
+    async execute(_toolCallId, params) {
+      const store = getStore();
+      const sourceTaskId = store.get(params.id)?.workflow?.activeTaskId;
+      const result = store.transitionWorkflow(params.id, {
+        outcome: params.outcome,
+        evidence: params.evidence,
+        activeTaskId: params.activeTaskId,
+      });
+      if (!result.applied || !result.entry) {
+        const current = store.get(params.id);
+        if (current?.workflow) {
+          return textResult(
+            `Workflow #${params.id} did not transition\n` +
+            `Reason: ${result.error ?? "unknown transition error"}\n` +
+            formatWorkflowSummary(current, `Workflow #${params.id} remains — ${current.status}`),
+            {
+              kind: "workflow",
+              action: "transition",
+              tone: "error",
+              summary: `Workflow #${params.id} remains in ${current.workflow.currentState}`,
+              expanded: [result.error ?? "unknown transition error"],
+            },
+          );
+        }
+        return textResult(result.error ?? `Workflow loop #${params.id} did not transition`);
+      }
+
+      const entry = result.entry;
+      getTriggerSystem().remove(entry.id);
+      const sourceTaskClosed = sourceTaskId ? await completeWorkflowTask?.(sourceTaskId) : undefined;
+      if (result.terminal === "completed") {
+        store.delete(entry.id);
+        updateWidget();
+        return textResult(
+          `Workflow #${entry.id} completed and deleted\n` +
+          `Final transition: ${entry.workflow?.lastTransition?.from ?? "?"} → ${entry.workflow?.currentState ?? "?"}\n` +
+          "Next: no further workflow transition is needed.",
+          {
+            kind: "workflow",
+            action: "transition",
+            tone: "success",
+            summary: `Workflow #${entry.id} completed${sourceTaskClosed ? ` · task #${sourceTaskId} closed` : ""}`,
+            expanded: [
+              `Final transition: ${entry.workflow?.lastTransition?.from ?? "?"} → ${entry.workflow?.currentState ?? "?"}`,
+              sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+            ],
+          },
+        );
+      }
+      if (result.terminal === "paused") {
+        store.pause(entry.id);
+        updateWidget();
+        return textResult(
+          `Workflow #${entry.id} paused\n` +
+          `Final state: ${entry.workflow?.currentState ?? "?"}\n` +
+          "Next: inspect it with WorkflowList before deciding whether to resume or delete it.",
+          {
+            kind: "workflow",
+            action: "transition",
+            tone: "warning",
+            summary: `Workflow #${entry.id} paused · ${entry.workflow?.currentState ?? "?"}`,
+            expanded: [
+              sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+              "Inspect WorkflowList before resuming or deleting this workflow.",
+            ],
+          },
+        );
+      }
+
+      const taskId = await createWorkflowTask?.(entry);
+      const updatedEntry = taskId ? store.setWorkflowActiveTask(entry.id, taskId) ?? entry : entry;
+      getTriggerSystem().add(updatedEntry);
+      updateWidget();
+      const from = updatedEntry.workflow?.lastTransition?.from ?? "?";
+      const to = updatedEntry.workflow?.currentState ?? "?";
+      return textResult(
+        `Workflow #${updatedEntry.id} advanced: ${from} → ${to}\n` +
+        formatWorkflowSummary(updatedEntry, `Workflow #${updatedEntry.id} — ${updatedEntry.status}`),
+        {
+          kind: "workflow",
+          action: "transition",
+          tone: "success",
+          summary: `Workflow #${updatedEntry.id} · ${from} → ${to}${taskId ? ` · task #${taskId}` : ""}`,
+          expanded: [
+            `Instruction: ${updatedEntry.workflow?.definition.states[to]?.prompt ?? ""}`,
+            `Outcome: ${Object.keys(updatedEntry.workflow?.definition.states[to]?.on ?? {}).join(", ") || "none"}`,
+            sourceTaskId ? `Source task #${sourceTaskId}: ${sourceTaskClosed ? "completed" : "not completed"}` : "Source task: none",
+          ],
+        },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "WorkflowList",
+    label: "WorkflowList",
+    renderCall: renderToolCall("Workflow", () => "status"),
+    renderResult: renderToolResult,
+    description: "List opt-in workflow loops with their current state, active task, and declared outcomes. Use this before WorkflowTransition when the current state is unclear.",
+    parameters: Type.Object({}),
+    execute() {
+      const workflows = getStore().list().filter((entry) => entry.workflow);
+      if (workflows.length === 0) {
+        return Promise.resolve(textResult(
+          "No workflow loops configured.\n" +
+          "Next: use WorkflowCreate for explicit state-and-outcome work, or LoopCreate for an ordinary schedule.",
+          { kind: "workflow", action: "list", tone: "info", summary: "No workflows", expanded: ["Use WorkflowCreate for state-and-outcome work."] },
+        ));
+      }
+
+      const lines = workflows.map((entry) => formatWorkflowSummary(entry, `Workflow #${entry.id} — ${entry.status}`));
+      return Promise.resolve(textResult(
+        `${workflows.length} workflow${workflows.length === 1 ? "" : "s"} configured\n\n${lines.join("\n\n")}`,
+        {
+          kind: "workflow",
+          action: "list",
+          tone: "info",
+          summary: `${workflows.length} workflow${workflows.length === 1 ? "" : "s"} · ${workflows.filter((entry) => entry.status === "active").length} active`,
+          expanded: displayRows(workflows.map((entry) => `#${entry.id} · ${entry.status} · ${entry.workflow?.currentState ?? "?"} · ${entry.prompt}`)),
+        },
       ));
     },
   });
@@ -320,13 +619,19 @@ Skip this tool when the task is a one-off check (just do it directly) or when th
   pi.registerTool({
     name: "LoopList",
     label: "LoopList",
+    renderCall: renderToolCall("Loop", () => "status"),
+    renderResult: renderToolResult,
     description: `List all active scheduled loops with their IDs, triggers, and next-fire times.
 
 Use this before creating new loops to avoid duplicates, or to find IDs for LoopDelete.`,
     parameters: Type.Object({}),
     execute() {
       const loops = getStore().list();
-      if (loops.length === 0) return Promise.resolve(textResult("No loops configured. Use LoopCreate to set up a schedule."));
+      if (loops.length === 0) {
+        return Promise.resolve(textResult("No loops configured. Use LoopCreate to set up a schedule.", {
+          kind: "loop", action: "list", tone: "info", summary: "No loops", expanded: ["Use LoopCreate to set up a schedule."],
+        }));
+      }
 
       const lines: string[] = [];
       for (const entry of loops) {
@@ -342,19 +647,28 @@ Use this before creating new loops to avoid duplicates, or to find IDs for LoopD
         }
         if (entry.autoTask) line += " [auto-task]";
         if (entry.taskBacklog) line += " [backlog-worker]";
+        if (entry.workflow) line += ` [workflow:${entry.workflow.currentState}]`;
         lines.push(line);
       }
 
-      return Promise.resolve(textResult(lines.join("\n")));
+      return Promise.resolve(textResult(lines.join("\n"), {
+        kind: "loop",
+        action: "list",
+        tone: "info",
+        summary: `${loops.length} loop${loops.length === 1 ? "" : "s"} · ${loops.filter((entry) => entry.status === "active").length} active`,
+        expanded: displayRows(lines),
+      }));
     },
   });
 
   pi.registerTool({
     name: "LoopUpdate",
     label: "LoopUpdate",
+    renderCall: renderToolCall("Loop", (args) => `update · #${String(toolArg(args, "id") ?? "?")} · ${String(toolArg(args, "status") ?? "continue")}`),
+    renderResult: renderToolResult,
     description: `Update progress for a dynamic loop.
 
-Use this after a dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval, "completed" when the goal is done, or "paused" to stop temporarily.`,
+Use this exactly once after each dynamic loop wake. Mark status as "continue" with updated state/metrics and optional nextInterval whenever any work remains, "completed" only when the overall goal and done criteria are satisfied, or "paused" when genuinely blocked. Do not use LoopDelete to finish an iteration.`,
     parameters: Type.Object({
       id: Type.String({ description: "Dynamic loop ID to update" }),
       status: Type.String({ description: "continue, completed, or paused", enum: ["continue", "completed", "paused"] }),
@@ -368,25 +682,49 @@ Use this after a dynamic loop wake. Mark status as "continue" with updated state
       const store = getStore();
       const triggerSystem = getTriggerSystem();
       const entry = store.get(params.id);
-      if (!entry) return Promise.resolve(textResult(`Loop #${params.id} not found`));
+      if (!entry) {
+        return Promise.resolve(textResult(`Loop #${params.id} not found`, {
+          kind: "loop", action: "update", tone: "error", summary: `Loop #${params.id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+        }));
+      }
       if (entry.trigger.type !== "dynamic" || !entry.dynamic) {
-        return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`));
+        return Promise.resolve(textResult(`Loop #${params.id} is not a dynamic loop`, {
+          kind: "loop", action: "update", tone: "error", summary: `Loop #${params.id} is not dynamic`, expanded: ["Use LoopUpdate only for dynamic loops."],
+        }));
       }
 
       const message = params.status === "continue"
         ? continueDynamicLoop(params, entry as LoopEntry & { dynamic: NonNullable<LoopEntry["dynamic"]> }, store, triggerSystem)
         : stopDynamicLoop(params, store, triggerSystem);
       updateWidget();
-      return Promise.resolve(textResult(message));
+      const tone = params.status === "paused" ? "warning" : "success";
+      const summary = params.status === "completed"
+        ? `Loop #${params.id} completed`
+        : params.status === "paused"
+          ? `Loop #${params.id} paused`
+          : `Loop #${params.id} updated`;
+      return Promise.resolve(textResult(message, {
+        kind: "loop",
+        action: "update",
+        tone,
+        summary,
+        expanded: params.status === "continue"
+          ? [`State: ${params.state ?? entry.dynamic.state ?? "unchanged"}`, `Next wake: ${params.nextInterval ?? "when idle"}`]
+          : [],
+      }));
     },
   });
 
   pi.registerTool({
     name: "LoopDelete",
     label: "LoopDelete",
+    renderCall: renderToolCall("Loop", (args) => `${String(toolArg(args, "action") ?? "delete")} · #${String(toolArg(args, "id") ?? "?")}`),
+    renderResult: renderToolResult,
     description: `Delete or pause a loop by its ID.
 
-Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.`,
+Use "pause" to temporarily stop a loop without removing it. Use "delete" to permanently remove it.
+
+Do not use this after a normal loop fire, an unchanged check, an empty iteration, or one step of a dynamic goal. Recurring loops remain active across iterations; dynamic loops use LoopUpdate. Delete only when the user explicitly asks to cancel the loop or its stated stop condition is satisfied.`,
     parameters: Type.Object({
       id: Type.String({ description: "Loop ID to delete or pause" }),
       action: Type.Optional(Type.String({ description: "delete or pause (default: delete)", enum: ["delete", "pause"], default: "delete" })),
@@ -398,21 +736,39 @@ Use "pause" to temporarily stop a loop without removing it. Use "delete" to perm
         const entry = getStore().pause(id);
         if (!entry) {
           const tombstone = getStore().getDeletionTombstone(id);
-          if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
-          return Promise.resolve(textResult(`Loop #${id} not found`));
+          if (tombstone) {
+            return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone), {
+              kind: "loop", action: "pause", tone: "warning", summary: `Loop #${id} was already removed`, expanded: [formatDeletionTombstone(id, tombstone)],
+            }));
+          }
+          return Promise.resolve(textResult(`Loop #${id} not found`, {
+            kind: "loop", action: "pause", tone: "error", summary: `Loop #${id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+          }));
         }
         getTriggerSystem().remove(id);
         updateWidget();
-        return Promise.resolve(textResult(`Loop #${id} paused`));
+        return Promise.resolve(textResult(`Loop #${id} paused`, {
+          kind: "loop", action: "pause", tone: "warning", summary: `Loop #${id} paused`, expanded: ["Use LoopList to inspect paused loops."],
+        }));
       }
 
       getTriggerSystem().remove(id);
       const deleted = getStore().delete(id);
       updateWidget();
-      if (deleted) return Promise.resolve(textResult(`Loop #${id} deleted`));
+      if (deleted) {
+        return Promise.resolve(textResult(`Loop #${id} deleted`, {
+          kind: "loop", action: "delete", tone: "success", summary: `Loop #${id} deleted`, expanded: [],
+        }));
+      }
       const tombstone = getStore().getDeletionTombstone(id);
-      if (tombstone) return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone)));
-      return Promise.resolve(textResult(`Loop #${id} not found`));
+      if (tombstone) {
+        return Promise.resolve(textResult(formatDeletionTombstone(id, tombstone), {
+          kind: "loop", action: "delete", tone: "warning", summary: `Loop #${id} was already removed`, expanded: [formatDeletionTombstone(id, tombstone)],
+        }));
+      }
+      return Promise.resolve(textResult(`Loop #${id} not found`, {
+        kind: "loop", action: "delete", tone: "error", summary: `Loop #${id} not found`, expanded: ["Use LoopList to find valid loop IDs."],
+      }));
     },
   });
 }

package/src/tools/monitor-tools.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { LoopEntry, MonitorEntry, Trigger } from "../types.js";
-import { textResult } from "./tool-result.js";
+import { renderToolCall, renderToolResult, toolArg } from "../ui/tool-renderer.js";
+import { displayRows, textResult } from "./tool-result.js";
 
 interface MonitorManagerLike {
   list(): MonitorEntry[];
@@ -39,6 +40,8 @@ export function registerMonitorTools(options: MonitorToolsOptions): void {
   pi.registerTool({
     name: "MonitorCreate",
     label: "MonitorCreate",
+    renderCall: renderToolCall("Monitor", (args) => `start · ${String(toolArg(args, "description") ?? toolArg(args, "command") ?? "monitor").slice(0, 56)}`),
+    renderResult: renderToolResult,
     description: `Run a shell command in the background and get notified when it finishes. The core tool for async/parallel work.
 
 Fire off a build check, CI monitor, experiment, script, or any slow command — then keep working. Output streams back as "monitor:output" events. When the process exits, "monitor:done" fires (or "monitor:error" on failure).
@@ -71,7 +74,9 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
     }),
     execute(_toolCallId, params) {
       if (getMonitorManager().list().filter((m) => m.status === "running").length >= 25) {
-        return Promise.resolve(textResult("Maximum of 25 running monitors reached. Stop some before creating new ones."));
+        return Promise.resolve(textResult("Maximum of 25 running monitors reached. Stop some before creating new ones.", {
+          kind: "monitor", action: "create", tone: "error", summary: "Monitor limit reached", expanded: ["Stop a running monitor before starting another."],
+        }));
       }
 
       const entry = getMonitorManager().create(params.command, params.description, params.timeout);
@@ -97,7 +102,18 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
       return Promise.resolve(textResult(
         `Monitor #${entry.id} started: ${entry.command.slice(0, 60)}\n` +
         `Output stream: monitor:output (monitorId: ${entry.id})\n` +
-        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`
+        `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}${onDoneMsg}`,
+        {
+          kind: "monitor",
+          action: "create",
+          tone: "success",
+          summary: `Monitor #${entry.id} running · ${params.description ?? entry.command.slice(0, 48)}`,
+          expanded: [
+            `Command: ${entry.command}`,
+            `Timeout: ${params.timeout ? `${params.timeout / 1000}s` : "none"}`,
+            params.onDone ? "Completion wake: enabled" : "Completion wake: off",
+          ],
+        },
       ));
     },
   });
@@ -105,11 +121,17 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
   pi.registerTool({
     name: "MonitorList",
     label: "MonitorList",
+    renderCall: renderToolCall("Monitor", () => "status"),
+    renderResult: renderToolResult,
     description: "List all monitors with their status, command, exit code, output line count, and last 5 lines of buffered output.",
     parameters: Type.Object({}),
     execute() {
       const monitors = getMonitorManager().list();
-      if (monitors.length === 0) return Promise.resolve(textResult("No monitors."));
+      if (monitors.length === 0) {
+        return Promise.resolve(textResult("No monitors.", {
+          kind: "monitor", action: "list", tone: "info", summary: "No monitors", expanded: ["Use MonitorCreate for long-running background work."],
+        }));
+      }
 
       const lines: string[] = [];
       for (const m of monitors) {
@@ -128,13 +150,22 @@ Pass onDone with a prompt and the monitor auto-creates a one-shot loop that fire
         }
       }
 
-      return Promise.resolve(textResult(lines.join("\n")));
+      const running = monitors.filter((monitor) => monitor.status === "running").length;
+      return Promise.resolve(textResult(lines.join("\n"), {
+        kind: "monitor",
+        action: "list",
+        tone: "info",
+        summary: `${monitors.length} monitor${monitors.length === 1 ? "" : "s"} · ${running} running`,
+        expanded: displayRows(lines),
+      }));
     },
   });
 
   pi.registerTool({
     name: "MonitorStop",
     label: "MonitorStop",
+    renderCall: renderToolCall("Monitor", (args) => `stop · #${String(toolArg(args, "monitorId") ?? "?")}`),
+    renderResult: renderToolResult,
     description: `Stop a running monitor. Sends SIGTERM, waits 5s, then SIGKILL.
 
 Use MonitorList to find the monitor ID, then stop it with this tool.`,
@@ -144,8 +175,14 @@ Use MonitorList to find the monitor ID, then stop it with this tool.`,
     async execute(_toolCallId, params) {
       const stopped = await getMonitorManager().stop(params.monitorId);
       updateWidget();
-      if (stopped) return textResult(`Monitor #${params.monitorId} stopped`);
-      return textResult(`Monitor #${params.monitorId} not found or not running`);
+      if (stopped) {
+        return textResult(`Monitor #${params.monitorId} stopped`, {
+          kind: "monitor", action: "stop", tone: "success", summary: `Monitor #${params.monitorId} stopped`, expanded: [],
+        });
+      }
+      return textResult(`Monitor #${params.monitorId} not found or not running`, {
+        kind: "monitor", action: "stop", tone: "error", summary: `Monitor #${params.monitorId} unavailable`, expanded: ["Use MonitorList to find running monitor IDs."],
+      });
     },
   });
 }