pi-quests 0.2.0 → 0.4.0

package/src/quest/formatters.ts

@@ -1,34 +1,49 @@
 export function formatQuestList(
-  quests: { id: number; description: string; done: boolean }[],
+  quests: { id: string; description: string; done: boolean; parentId?: string }[],
 ): string {
   if (quests.length === 0) return "No quests.";
-  return quests.map((q) => `#${q.id} [${q.done ? "x" : " "}] ${q.description}`).join("\n");
+
+  const lines: string[] = [];
+  let pos = 1;
+  for (const q of quests) {
+    if (q.parentId) {
+      lines.push(`   [${q.id}] [${q.done ? "x" : " "}] ${q.description}`);
+    } else {
+      lines.push(`#${pos} [${q.id}] [${q.done ? "x" : " "}] ${q.description}`);
+      pos++;
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatAddResult(q: { id: string; description: string }): string {
+  return `Added quest [${q.id}]: ${q.description}`;
 }
 
-export function formatAddResult(q: { id: number; description: string }): string {
-  return `Added quest #${q.id}: ${q.description}`;
+export function formatBatchAddResult(added: { id: string; description: string }[]): string {
+  return `Added ${added.length} quests:\n${added.map((q) => `[${q.id}]: ${q.description}`).join("\n")}`;
 }
 
-export function formatBatchAddResult(added: { id: number; description: string }[]): string {
-  return `Added ${added.length} quests:\n${added.map((q) => `#${q.id}: ${q.description}`).join("\n")}`;
+export function formatToggleResult(id: string, done: boolean): string {
+  return `Quest [${id}] ${done ? "done" : "undone"}`;
 }
 
-export function formatToggleResult(id: number, done: boolean): string {
-  return `Quest #${id} ${done ? "done" : "undone"}`;
+export function formatUpdateResult(q: { id: string; description: string }): string {
+  return `Updated quest [${q.id}]: ${q.description}`;
 }
 
-export function formatUpdateResult(q: { id: number; description: string }): string {
-  return `Updated quest #${q.id}: ${q.description}`;
+export function formatDeleteResult(q: { id: string; description: string }): string {
+  return `Deleted quest [${q.id}]: ${q.description}`;
 }
 
-export function formatDeleteResult(q: { id: number; description: string }): string {
-  return `Deleted quest #${q.id}: ${q.description}`;
+export function formatNotFound(id: string): string {
+  return `Quest [${id}] not found`;
 }
 
-export function formatClearResult(count: number): string {
-  return `Cleared ${count} quests`;
+export function formatBlockedBySubQuests(id: string): string {
+  return `Quest [${id}] has incomplete sub-quests`;
 }
 
-export function formatNotFound(id: number): string {
-  return `Quest #${id} not found`;
+export function formatSubQuestCannotHaveSubQuests(id: string): string {
+  return `Sub-quest [${id}] cannot have nested sub-quests`;
 }

package/src/quest/tracker.ts

@@ -1,20 +1,7 @@
-export const COMPLEX_TASK_KEYWORDS = [
-  "implement",
-  "refactor",
-  "investigate",
-  "review",
-  "analyze",
-  "audit",
-  "plan",
-  "design",
-  "create",
-  "build",
-  "write",
-  "fix",
-] as const;
+import type { ResolvedConfig } from "../config.js";
 
 const ACKNOWLEDGEMENT =
-  "ALWAYS acknowledge this reminder and create, update, or align on quests before making further tool calls.";
+  "ALWAYS acknowledge this reminder immediately and create, update, or align on quests before making further tool calls. DO NOT add this acknowledgement as another quest.";
 
 export class QuestUsageTracker {
   private totalToolCalls = 0;
@@ -23,6 +10,8 @@ export class QuestUsageTracker {
   private lastQuestToolTime = 0;
   private nudgedThisTurn = false;
 
+  constructor(private readonly config: ResolvedConfig) {}
+
   onToolExecution(toolName: string): void {
     this.totalToolCalls++;
     if (toolName === "quest") {
@@ -38,11 +27,15 @@ export class QuestUsageTracker {
     this.nudgedThisTurn = false;
   }
 
-  getNudge(activeQuestCount: number, latestPrompt?: string): string | undefined {
+  getNudge(
+    activeQuestCount: number,
+    latestPrompt?: string,
+    hasTopLevelQuestWithoutSubs?: boolean,
+  ): string | undefined {
     if (this.nudgedThisTurn) return undefined;
 
     // 1. Initialization nudge
-    if (this.totalToolCalls >= 3 && !this.hasEverUsedQuestTool) {
+    if (this.totalToolCalls >= this.config.nudges.toolCallThreshold && !this.hasEverUsedQuestTool) {
       this.nudgedThisTurn = true;
       return `QUEST REMINDER: You have made ${this.totalToolCalls} tool calls but have NEVER used the quest tool this session. USE the quest tool to initialize tracking and break your work into concrete steps. ${ACKNOWLEDGEMENT}`;
     }
@@ -57,24 +50,40 @@ export class QuestUsageTracker {
     if (
       this.hasEverUsedQuestTool &&
       this.lastQuestToolTime > 0 &&
-      this.consecutiveNonQuestToolCalls >= 3 &&
-      // 8 minutes without quest tool use
-      Date.now() - this.lastQuestToolTime >= 8 * 60 * 1000
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.timeBasedToolCallThreshold &&
+      Date.now() - this.lastQuestToolTime >= this.config.nudges.hintIntervalMinutes * 60 * 1000
     ) {
       this.nudgedThisTurn = true;
       return `QUEST REMINDER: It has been a while since your last quest tool use and ${this.consecutiveNonQuestToolCalls} tools have been called since then. ALIGN on quest status before continuing. ${ACKNOWLEDGEMENT}`;
     }
 
     // 4. Zero-active sustained-work nudge
-    if (this.consecutiveNonQuestToolCalls >= 5 && activeQuestCount === 0) {
+    if (
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.zeroActiveToolCallThreshold &&
+      activeQuestCount === 0
+    ) {
       this.nudgedThisTurn = true;
       return `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and there are 0 active quests. TRACK your work with specific, actionable quests. ${ACKNOWLEDGEMENT}`;
     }
 
-    // 5. Stale-progress sustained-work nudge
-    if (this.consecutiveNonQuestToolCalls >= 10 && activeQuestCount > 0) {
+    // 5. Sub-quest suggestion nudge
+    if (
+      this.hasEverUsedQuestTool &&
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.subQuestSuggestionToolCallThreshold &&
+      activeQuestCount > 0 &&
+      hasTopLevelQuestWithoutSubs
+    ) {
+      this.nudgedThisTurn = true;
+      return `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and have active top-level quests without sub-quests. Use the \`add\` action with \`parentId\` to break down complex tasks into smaller, trackable steps. ${ACKNOWLEDGEMENT}`;
+    }
+
+    // 6. Stale-progress sustained-work nudge
+    if (
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.staleProgressToolCallThreshold &&
+      activeQuestCount > 0
+    ) {
       this.nudgedThisTurn = true;
-      return `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool despite having active quests. UPDATE your quest progress to reflect current status. ${ACKNOWLEDGEMENT}`;
+      return `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool despite having active quests.\nUPDATE your quest progress to reflect current status.\nALWAYS use sub quests to break down a quest into smaller steps, and to group related tasks together. ${ACKNOWLEDGEMENT}`;
     }
 
     return undefined;
@@ -82,6 +91,6 @@ export class QuestUsageTracker {
 
   private isComplexPrompt(prompt: string): boolean {
     const lower = prompt.toLowerCase();
-    return COMPLEX_TASK_KEYWORDS.some((kw) => lower.includes(kw));
+    return this.config.nudges.complexTaskKeywords.some((kw) => lower.includes(kw));
   }
 }

package/src/quest/types.ts

@@ -9,6 +9,7 @@ export const QUEST_ACTIONS = {
   update: "update",
   delete: "delete",
   clear: "clear",
+  reorder: "reorder",
   revert: "revert",
 } as const;
 
@@ -19,15 +20,19 @@ export const QUEST_ACTION_VALUES = [
   QUEST_ACTIONS.update,
   QUEST_ACTIONS.delete,
   QUEST_ACTIONS.clear,
+  QUEST_ACTIONS.reorder,
   QUEST_ACTIONS.revert,
 ] as const;
 
 export type QuestActionType = (typeof QUEST_ACTION_VALUES)[number];
 
 export interface Quest {
-  id: number;
+  id: string;
   description: string;
-  additionalContext?: string;
   done: boolean;
   createdAt: number;
 }
+
+export interface SubQuest extends Quest {
+  parentId: string;
+}

package/src/renderers/commands.ts

@@ -1,20 +1,22 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
-import type { Quest } from "../quest/types.js";
+import type { QuestLog } from "../quest/dataplane.js";
+import { formatQuestRow, formatSubQuestSpacerLine } from "./quests.js";
 
 export class QuestListWidget {
   private cachedWidth?: number;
   private cachedLines?: string[];
   private page = 0;
-  private readonly pageSize = 10;
 
   constructor(
-    private quests: Quest[],
+    private questLog: QuestLog,
     private theme: Theme,
     private onClose: () => void,
+    private readonly config: ResolvedConfig,
   ) {
-    logger.debug("quests:widget", "create", { questCount: quests.length });
+    logger.debug("quests:widget", "create", { questCount: questLog.getAll().length });
   }
 
   handleInput(data: string): void {
@@ -37,7 +39,35 @@ export class QuestListWidget {
   }
 
   private get totalPages(): number {
-    return Math.max(1, Math.ceil(this.quests.length / this.pageSize));
+    const totalLines = this.buildQuestLines(0).length;
+    return Math.max(1, Math.ceil(totalLines / this.config.display.pageSize));
+  }
+
+  private buildQuestLines(width: number): string[] {
+    const th = this.theme;
+    const parents = this.questLog.getQuests();
+    const lines: string[] = [];
+
+    for (let i = 0; i < parents.length; i++) {
+      const parent = parents[i];
+      const subs = this.questLog.getSubQuests(parent.id);
+
+      const row = formatQuestRow(th, parent, this.config.ids.length, i + 1);
+      lines.push(width > 0 ? truncateToWidth(row, width) : row);
+
+      if (subs.length > 0) {
+        lines.push(formatSubQuestSpacerLine(th, this.config.ids.length));
+
+        for (const sub of subs) {
+          const subRow = formatQuestRow(th, sub, this.config.ids.length);
+          lines.push(width > 0 ? truncateToWidth(subRow, width) : subRow);
+        }
+
+        lines.push("");
+      }
+    }
+
+    return lines;
   }
 
   private nextPage(): void {
@@ -72,13 +102,14 @@ export class QuestListWidget {
       width,
       page: this.page,
       totalPages: this.totalPages,
-      totalQuests: this.quests.length,
+      totalQuests: this.questLog.getAll().length,
     });
 
     const th = this.theme;
     const lines: string[] = [];
-    const total = this.quests.length;
-    const doneCount = this.quests.filter((q) => q.done).length;
+    const allQuests = this.questLog.getAll();
+    const total = allQuests.length;
+    const doneCount = allQuests.filter((q) => q.done).length;
 
     // Top accent border
     lines.push(th.fg("accent", "─".repeat(width)));
@@ -91,7 +122,7 @@ export class QuestListWidget {
 
     lines.push("");
 
-    if (this.quests.length === 0) {
+    if (total === 0) {
       lines.push(
         truncateToWidth(
           `  ${th.fg("dim", "No active quests. Add one with /quests add <description>")}`,
@@ -100,7 +131,7 @@ export class QuestListWidget {
       );
     } else {
       // Mini progress bar
-      const barWidth = Math.min(width - 4, 24);
+      const barWidth = Math.min(width - 4, this.config.display.progressBarMaxWidth);
       const filled = Math.round((doneCount / total) * barWidth);
       const empty = barWidth - filled;
       const bar = th.fg("success", "█".repeat(filled)) + th.fg("dim", "░".repeat(empty));
@@ -108,18 +139,11 @@ export class QuestListWidget {
       lines.push(truncateToWidth(`  ${bar}  ${th.fg("muted", `${doneCount}/${total}`)}`, width));
       lines.push("");
 
-      const start = this.page * this.pageSize;
-      const pageQuests = this.quests.slice(start, start + this.pageSize);
-      for (const q of pageQuests) {
-        const marker = q.done ? th.fg("success", "  ✓ ") : th.fg("muted", "  ○ ");
-        const idStr = th.fg(q.done ? "dim" : "accent", `#${q.id}`);
-        const desc = q.done
-          ? th.fg("dim", th.strikethrough(q.description))
-          : th.fg("text", q.description);
-        const row = `${marker}${idStr} ${desc}`;
-
-        lines.push(truncateToWidth(row, width));
-      }
+      const questLines = this.buildQuestLines(width);
+      const start = this.page * this.config.display.pageSize;
+      const pageLines = questLines.slice(start, start + this.config.display.pageSize);
+
+      lines.push(...pageLines);
 
       if (this.totalPages > 1) {
         const pageInfo = `  Page ${this.page + 1}/${this.totalPages}  ${th.fg("dim", "· Tab/Shift+Tab to navigate")}`;

package/src/renderers/quests.ts

@@ -0,0 +1,45 @@
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { visibleWidth } from "@mariozechner/pi-tui";
+import type { Quest, SubQuest } from "../quest/types.js";
+
+export function formatQuestRow(
+  theme: Theme,
+  q: Quest | SubQuest,
+  idLength: number,
+  pos?: number,
+): string {
+  const isSub = "parentId" in q && q.parentId;
+
+  // position test is only relevant for quests, not subquests
+  const posText = isSub ? "" : pos !== undefined ? `#${pos}` : "";
+  const posWidth = visibleWidth(posText);
+  const idText = `[${q.id}]`;
+
+  // spacing is added to keep text aligned
+  const spacing = " ".repeat(visibleWidth(`${16 ** idLength}`) - posWidth);
+  const idStr = `${theme.fg("muted", idText)} ${theme.fg(q.done ? "dim" : "accent", `${posText}`)}${spacing}`;
+
+  // for subquests, use a different marker and indent
+  const markerNotDone = isSub ? theme.fg("muted", " └── ○ ") : theme.fg("muted", " ○ ");
+  const markerDone = isSub ? theme.fg("muted", " └── ✓ ") : theme.fg("success", " ✓ ");
+  const marker = q.done ? markerDone : markerNotDone;
+
+  // for subquests, use dim text to contrast with the parent quests
+  const descColor = q.done || isSub ? "dim" : "text";
+  const desc = q.done
+    ? theme.fg(descColor, theme.strikethrough(q.description))
+    : theme.fg(descColor, q.description);
+
+  const line = `  ${idStr}${marker} ${desc}`;
+  return line;
+}
+
+export function formatSubQuestSpacerLine(theme: Theme, idLength: number): string {
+  const idTextLength = visibleWidth(`${16 ** idLength}`);
+  // spacing for `[id](position string)`
+  const spacerStr = `${" ".repeat(idTextLength + 2)}${" ".repeat(idTextLength)}`;
+
+  const marker = theme.fg("muted", " │   ");
+
+  return `  ${spacerStr}${marker}`;
+}

package/src/renderers/tools.ts

@@ -1,18 +1,26 @@
 import type { AgentToolResult, Theme } from "@mariozechner/pi-coding-agent";
 import { Text } from "@mariozechner/pi-tui";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
+import type { Quest } from "../quest/types.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
+import { formatQuestRow, formatSubQuestSpacerLine } from "./quests.js";
 
 type QuestArgs = {
   action: string;
   descriptions?: string[];
-  id?: number;
+  targetId?: string;
+  id?: string;
+  all?: boolean;
 };
 
 export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown): Text {
   const id = "id" in args ? args.id : undefined;
   logger.debug("quests:tool", "renderCall", { action: args.action, id });
-  const actionText = theme.fg("toolTitle", theme.bold("quest ")) + theme.fg("accent", args.action);
+  const actionText =
+    theme.fg("toolTitle", theme.bold("quest ")) +
+    theme.fg("accent", args.action) +
+    theme.fg("muted", args.targetId ? ` ${args.targetId}` : "");
 
   if (args.action === QUEST_ACTIONS.add && args.descriptions && args.descriptions.length > 0) {
     const n = args.descriptions.length;
@@ -29,36 +37,82 @@ export function renderQuestCall(args: QuestArgs, theme: Theme, _context: unknown
       args.action === QUEST_ACTIONS.delete) &&
     args.id !== undefined
   ) {
-    return new Text(`${actionText} ${theme.fg("muted", `#${args.id}`)}`, 0, 0);
+    return new Text(`${actionText} ${theme.fg("muted", `[${args.id}]`)}`, 0, 0);
+  }
+
+  if (args.action === QUEST_ACTIONS.clear) {
+    return new Text(`${actionText} ${theme.fg("muted", `[${args.all ? "all" : "done"}]`)}`, 0, 0);
   }
 
   return new Text(actionText, 0, 0);
 }
 
-export function renderQuestResult(
-  result: AgentToolResult<unknown>,
-  options: { expanded: boolean; isPartial: boolean },
-  theme: Theme,
-  _context: unknown,
-): Text {
-  logger.debug("quests:tool", "renderResult", {
-    expanded: options.expanded,
-    isPartial: options.isPartial,
-  });
-  const details = result.details as Record<string, unknown> | undefined;
-  const questsToRender = details?.displayQuests ?? details?.quests;
-
-  if (Array.isArray(questsToRender) && questsToRender.length > 0) {
-    const lines = (questsToRender as Array<{ id: number; description: string; done: boolean }>).map(
-      (q) => {
-        const marker = q.done ? theme.fg("success", "✓") : theme.fg("dim", "○");
-        return `${marker} ${theme.fg("text", `#${q.id}`)} ${theme.fg("muted", q.description)}`;
-      },
-    );
+export function renderQuestResult(config: ResolvedConfig) {
+  return (
+    result: AgentToolResult<unknown>,
+    options: { expanded: boolean; isPartial: boolean },
+    theme: Theme,
+    _context: unknown,
+  ): Text => {
+    logger.debug("quests:tool", "renderResult", {
+      expanded: options.expanded,
+      isPartial: options.isPartial,
+    });
+    const details = result.details as Record<string, unknown> | undefined;
+    const allQuests = details?.quests as Quest[] | undefined;
+    const questsToRender = (details?.displayQuests ?? details?.quests) as Quest[] | undefined;
 
-    return new Text(lines.join("\n"), 0, 0);
-  }
+    if (
+      !Array.isArray(questsToRender) ||
+      questsToRender.length === 0 ||
+      !Array.isArray(allQuests)
+    ) {
+      const text = result.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("\n");
+      return new Text(theme.fg("text", text), 0, 0);
+    }
+
+    const quests = allQuests;
+    const renderedIds = new Set(questsToRender.map((q) => q.id));
+    const parents = quests.filter((q) => !(q as Quest & { parentId?: string }).parentId);
+    const lines: string[] = [];
+
+    function getSubQuests(parentId: string) {
+      return quests.filter((q) => (q as Quest & { parentId?: string }).parentId === parentId);
+    }
+
+    function willRenderLater(idx: number): boolean {
+      for (let j = idx + 1; j < parents.length; j++) {
+        const p = parents[j];
+        if (renderedIds.has(p.id)) return true;
 
-  const text = result.content.map((c) => (c.type === "text" ? c.text : "[image]")).join("\n");
-  return new Text(theme.fg("text", text), 0, 0);
+        const subs = getSubQuests(p.id).filter((sq) => renderedIds.has(sq.id));
+        if (subs.length > 0) return true;
+      }
+
+      return false;
+    }
+
+    for (let i = 0; i < parents.length; i++) {
+      const parent = parents[i];
+      const parentIncluded = renderedIds.has(parent.id);
+      const includedSubs = getSubQuests(parent.id).filter((sq) => renderedIds.has(sq.id));
+
+      if (!parentIncluded && includedSubs.length === 0) continue;
+
+      if (parentIncluded) {
+        lines.push(formatQuestRow(theme, parent, config.ids.length, i + 1));
+        if (includedSubs.length > 0) lines.push(formatSubQuestSpacerLine(theme, config.ids.length));
+      }
+
+      for (const sub of includedSubs) {
+        lines.push(formatQuestRow(theme, sub, config.ids.length));
+      }
+
+      if (includedSubs.length > 0 && willRenderLater(i)) {
+        lines.push("");
+      }
+    }
+
+    return new Text(lines.join("\n"), 0, 0);
+  };
 }

package/src/tools/handler.ts

@@ -1,12 +1,14 @@
 import type { AgentToolResult, ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import type { Static } from "@sinclair/typebox";
+import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
+import { QUEST_PROMPT_GATE, QUEST_PROMPT_REMINDER } from "../prompts.js";
 import { makeToolResult, type QuestAction, type QuestLog } from "../quest/dataplane.js";
 import { QUEST_ACTIONS } from "../quest/types.js";
 import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
-import { QuestParams } from "./params.js";
+import { createQuestParams, type QuestParamsType } from "./params.js";
 
-type QuestToolParams = Static<typeof QuestParams>;
+type QuestToolParams = Static<QuestParamsType>;
 
 const toolHandlers: {
   [K in QuestToolParams["action"]]: (
@@ -19,6 +21,7 @@ const toolHandlers: {
     return runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.add,
       descriptions: params.descriptions,
+      parentId: params.parentId,
     });
   },
   [QUEST_ACTIONS.list](questLog, _params, toolCallId) {
@@ -37,8 +40,15 @@ const toolHandlers: {
   [QUEST_ACTIONS.delete](questLog, params, toolCallId) {
     return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.delete, id: params.id });
   },
-  [QUEST_ACTIONS.clear](questLog, _params, toolCallId) {
-    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.clear });
+  [QUEST_ACTIONS.clear](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.clear, all: params.all });
+  },
+  [QUEST_ACTIONS.reorder](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.reorder,
+      id: params.id,
+      targetId: params.targetId,
+    });
   },
   [QUEST_ACTIONS.revert](questLog, _params, toolCallId) {
     return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.revert });
@@ -75,26 +85,24 @@ export async function questToolExecute(
   return handler(questLog, params, toolCallId);
 }
 
-export function registerQuestTool(pi: ExtensionAPI, questLog: QuestLog): void {
+export function registerQuestTool(
+  pi: ExtensionAPI,
+  questLog: QuestLog,
+  config: ResolvedConfig,
+): void {
   logger.debug("quests:tool", "register");
   pi.registerTool({
     name: "quest",
     label: "Quest",
     description:
-      "Manage the session quest log. Use this VERY frequently to track tasks, plans, and progress throughout the conversation.",
-    promptSnippet: "Add, list, toggle, update, delete, clear, or revert quest items",
-    promptGuidelines: [
-      "Before reading files, running commands, or making edits, ensure the current work is tracked as specific, actionable quests.",
-      "Do not create a single vague quest for broad requests. Break them into concrete, independent steps.",
-      "When the user gives a plan or a list of tasks, add them as quests immediately.",
-      "It is critical that you toggle quests to done as soon as you complete them. Do NOT batch completions.",
-      "Before delegating to a minion, add a quest for the delegated task.",
-      "If you are unsure what to do next, use the list action to check active quests.",
-    ],
-    parameters: QuestParams,
+      "Manage the session quest log including top-level quests and sub-quests. Use this VERY frequently to track tasks, plans, and progress throughout the conversation.",
+    promptSnippet:
+      "Add (with optional parentId for sub-quests), list, toggle, update, delete, clear, or revert quest items",
+    promptGuidelines: [...QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
+    parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>
       questToolExecute(questLog, toolCallId, params),
     renderCall: renderQuestCall,
-    renderResult: renderQuestResult,
+    renderResult: renderQuestResult(config),
   });
 }

package/src/tools/params.ts

@@ -2,23 +2,48 @@ import { StringEnum } from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
 import { QUEST_ACTION_VALUES } from "../quest/types.js";
 
-export const QuestParams = Type.Object({
-  action: StringEnum(QUEST_ACTION_VALUES, {
-    description: "The quest action to perform",
-  }),
-  descriptions: Type.Optional(
-    Type.Array(Type.String(), {
-      description: "Array of quest descriptions (required for add action)",
+export function createQuestParams(idLength: number) {
+  const pattern = `^[0-9a-f]{${idLength}}$`;
+  return Type.Object({
+    action: StringEnum(QUEST_ACTION_VALUES, {
+      description: "The quest action to perform",
     }),
-  ),
-  description: Type.Optional(
-    Type.String({
-      description: "New description (required for update action)",
-    }),
-  ),
-  id: Type.Optional(
-    Type.Number({
-      description: "Quest ID (required for toggle, update, delete actions)",
-    }),
-  ),
-});
+    descriptions: Type.Optional(
+      Type.Array(Type.String(), {
+        description: "Array of quest descriptions (required for add action)",
+      }),
+    ),
+    description: Type.Optional(
+      Type.String({
+        description: "New description (required for update action)",
+      }),
+    ),
+    parentId: Type.Optional(
+      Type.String({
+        pattern,
+        description:
+          "Parent quest hex ID. Use this to break a large task into smaller, trackable steps. When provided, the added quest becomes a sub-quest under the parent.",
+      }),
+    ),
+    id: Type.Optional(
+      Type.String({
+        pattern,
+        description: `Quest ID (required for toggle, update, delete, reorder actions). ALWAYS use the ${idLength}-digit hex ID shown in brackets, never the positional number.`,
+      }),
+    ),
+    targetId: Type.Optional(
+      Type.String({
+        pattern,
+        description:
+          "Target quest ID for reorder action. The quest will be moved to just before the target quest.",
+      }),
+    ),
+    all: Type.Optional(
+      Type.Boolean({
+        description: "Clear all quests when true (defaults to clearing only completed quests)",
+      }),
+    ),
+  });
+}
+
+export type QuestParamsType = ReturnType<typeof createQuestParams>;