pi-quests 0.4.0 → 0.5.0

package/src/quest/formatters.ts

@@ -1,3 +1,19 @@
+/**
+ * Error message design guidelines
+ *
+ * All error messages should follow a consistent three-part pattern:
+ *   1. PROBLEM — state what went wrong clearly and concisely
+ *   2. RULE    — explain the constraint or invariant that was violated
+ *   3. RECOVERY HINT — suggest the next valid action the caller can take
+ *
+ * Example:
+ *   "Quest [01] has incomplete steps. A parent quest can only be marked
+ *    done after all its steps are complete. Try toggling the steps first."
+ *
+ * Keep messages actionable. Agents should never be left guessing why something
+ * failed or what to do next.
+ */
+
 export function formatQuestList(
   quests: { id: string; description: string; done: boolean; parentId?: string }[],
 ): string {
@@ -37,13 +53,86 @@ export function formatDeleteResult(q: { id: string; description: string }): stri
 }
 
 export function formatNotFound(id: string): string {
-  return `Quest [${id}] not found`;
+  return `Quest [${id}] not found. IDs are random hex strings shown in brackets. Use the list action to see valid IDs.`;
+}
+
+export function formatBlockedBySteps(id: string): string {
+  return `Quest [${id}] has incomplete steps. A parent quest can only be marked done or deleted after all its steps are complete. Toggle the steps first, or delete them if they are no longer needed.`;
+}
+
+export function formatStepCannotHaveSteps(id: string): string {
+  return `Step [${id}] cannot have nested steps. The quest system only supports one level of nesting. Use a top-level quest as the parent instead.`;
+}
+
+export function formatEmptyDescriptionsError(): string {
+  return `Every description in a batch must be non-empty. Remove empty strings or split the batch into separate add calls.`;
+}
+
+export function formatMissingDescriptionsError(action = "add"): string {
+  return `At least one description is required for the ${action} action. Provide a description string to create a quest.`;
+}
+
+export function formatIdRequiredError(action: string): string {
+  return `An id is required for the ${action} action. Use the list action to see valid quest IDs. IDs are the hex strings shown in square brackets.`;
+}
+
+export function formatDescriptionRequiredError(): string {
+  return `A description is required for the update action. Provide a non-empty string to update the quest.`;
+}
+
+export function formatTargetIdRequiredError(): string {
+  return `A targetId is required for the reorder action. Provide the hex ID of the quest to insert before.`;
+}
+
+export function formatReorderNotFoundError(): string {
+  return `Quest not found or is a step. Reorder only works on top-level quests. Use the list action to verify the ID and ensure it is a top-level quest.`;
+}
+
+export function formatParentNotFoundError(id: string): string {
+  return `Parent quest [${id}] not found. Use the list action to see valid parent IDs.`;
+}
+
+export function formatParentDoneError(id: string): string {
+  return `Cannot add a step to completed parent quest [${id}]. Steps can only be added to open parents. Reopen the parent first if you need to add more work.`;
+}
+
+export function formatUnknownActionError(action: string): string {
+  return `Unknown action: ${action}. Use the list action or check the tool schema for supported actions.`;
+}
+
+export function formatNothingToRevertError(): string {
+  return `Nothing to revert. The history is empty because no mutating actions have been performed yet.`;
+}
+
+export function formatReorderedQuestNotFoundError(): string {
+  return `Reordered quest not found. It may have been deleted or cleared since the reorder was recorded.`;
+}
+
+export function formatReparentResult(
+  q: { id: string; description: string },
+  parentId?: string,
+): string {
+  return parentId
+    ? `Moved quest [${q.id}] under [${parentId}]: ${q.description}`
+    : `Promoted quest [${q.id}] to top-level: ${q.description}`;
+}
+
+export function formatReparentTargetNotFoundError(id: string): string {
+  return `Target quest [${id}] not found. Use the list action to see valid parent IDs.`;
+}
+
+export function formatReparentTargetIsStepError(id: string): string {
+  return `Step [${id}] cannot be a parent. The quest system only supports one level of nesting. Use a top-level quest as the parent instead.`;
+}
+
+export function formatReparentTargetDoneError(id: string): string {
+  return `Cannot reparent under completed parent [${id}]. Steps can only be added to open parents.`;
 }
 
-export function formatBlockedBySubQuests(id: string): string {
-  return `Quest [${id}] has incomplete sub-quests`;
+export function formatReparentDemoteHasStepsError(id: string): string {
+  return `Quest [${id}] has steps and cannot be demoted to a step. Delete or reparent its steps first.`;
 }
 
-export function formatSubQuestCannotHaveSubQuests(id: string): string {
-  return `Sub-quest [${id}] cannot have nested sub-quests`;
+export function formatReparentSelfParentError(id: string): string {
+  return `Quest [${id}] cannot be its own parent. Choose a different parent ID.`;
 }

package/src/quest/tracker.ts

@@ -1,7 +1,8 @@
 import type { ResolvedConfig } from "../config.js";
 
-const ACKNOWLEDGEMENT =
-  "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.";
+const ACKNOWLEDGEMENT = "Update your quest status before continuing.";
+
+type NudgeCandidate = { index: number; message: string };
 
 export class QuestUsageTracker {
   private totalToolCalls = 0;
@@ -9,6 +10,8 @@ export class QuestUsageTracker {
   private hasEverUsedQuestTool = false;
   private lastQuestToolTime = 0;
   private nudgedThisTurn = false;
+  private lastNudgeTime = 0;
+  private lastNudgeIndex = -1;
 
   constructor(private readonly config: ResolvedConfig) {}
 
@@ -34,59 +37,107 @@ export class QuestUsageTracker {
   ): string | undefined {
     if (this.nudgedThisTurn) return undefined;
 
-    // 1. Initialization nudge
-    if (this.totalToolCalls >= this.config.nudges.toolCallThreshold && !this.hasEverUsedQuestTool) {
+    const now = Date.now();
+    const cooldownMs = this.config.nudges.hintIntervalMinutes * 60 * 1000;
+    if (this.lastNudgeTime > 0 && now - this.lastNudgeTime < cooldownMs) {
+      return undefined;
+    }
+
+    const eligible = this.getEligibleNudges(
+      activeQuestCount,
+      latestPrompt,
+      hasTopLevelQuestWithoutSubs,
+    );
+
+    // Rotate priority: start checking from the nudge after the last one that fired
+    const rotated = [
+      ...eligible.filter((n) => n.index > this.lastNudgeIndex),
+      ...eligible.filter((n) => n.index <= this.lastNudgeIndex),
+    ];
+
+    const winner = rotated[0];
+    if (winner) {
       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}`;
+      this.lastNudgeTime = now;
+      this.lastNudgeIndex = winner.index;
+      return winner.message;
+    }
+
+    return undefined;
+  }
+
+  private getEligibleNudges(
+    activeQuestCount: number,
+    latestPrompt?: string,
+    hasTopLevelQuestWithoutSubs?: boolean,
+  ): NudgeCandidate[] {
+    const candidates: NudgeCandidate[] = [];
+
+    // 0. Initialization nudge
+    if (this.totalToolCalls >= this.config.nudges.toolCallThreshold && !this.hasEverUsedQuestTool) {
+      candidates.push({
+        index: 0,
+        message: `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}`,
+      });
     }
 
-    // 2. Complex-task entrypoint nudge
+    // 1. Complex-task entrypoint nudge
     if (activeQuestCount === 0 && latestPrompt && this.isComplexPrompt(latestPrompt)) {
-      this.nudgedThisTurn = true;
-      return `QUEST REMINDER: Your latest prompt appears to be a complex task, but there are 0 active quests. USE the quest tool to break this into concrete, trackable steps. ${ACKNOWLEDGEMENT}`;
+      candidates.push({
+        index: 1,
+        message: `QUEST REMINDER: Your latest prompt appears to be a complex task, but there are 0 active quests. USE the quest tool to break this into concrete, trackable steps. ${ACKNOWLEDGEMENT}`,
+      });
     }
 
-    // 3. Time-based alignment nudge
+    // 2. Time-based alignment nudge
     if (
       this.hasEverUsedQuestTool &&
       this.lastQuestToolTime > 0 &&
       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}`;
+      candidates.push({
+        index: 2,
+        message: `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
+    // 3. Zero-active sustained-work nudge
     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}`;
+      candidates.push({
+        index: 3,
+        message: `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. Sub-quest suggestion nudge
+    // 4. Sub-quest suggestion nudge
     if (
       this.hasEverUsedQuestTool &&
-      this.consecutiveNonQuestToolCalls >= this.config.nudges.subQuestSuggestionToolCallThreshold &&
+      this.consecutiveNonQuestToolCalls >= this.config.nudges.stepSuggestionToolCallThreshold &&
       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}`;
+      candidates.push({
+        index: 4,
+        message: `QUEST REMINDER: You have made ${this.consecutiveNonQuestToolCalls} consecutive tool calls without using the quest tool and have active top-level quests without steps. Use the \`split\` action to break down complex tasks into smaller, trackable steps. ${ACKNOWLEDGEMENT}`,
+      });
     }
 
-    // 6. Stale-progress sustained-work nudge
+    // 5. 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.\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}`;
+      candidates.push({
+        index: 5,
+        message: `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 steps to break down a quest into smaller steps, and to group related tasks together. ${ACKNOWLEDGEMENT}`,
+      });
     }
 
-    return undefined;
+    return candidates;
   }
 
   private isComplexPrompt(prompt: string): boolean {

package/src/quest/types.ts

@@ -11,6 +11,11 @@ export const QUEST_ACTIONS = {
   clear: "clear",
   reorder: "reorder",
   revert: "revert",
+  reparent: "reparent",
+  rules: "rules",
+  skill: "skill",
+  split: "split",
+  add_step: "add_step",
 } as const;
 
 export const QUEST_ACTION_VALUES = [
@@ -22,6 +27,11 @@ export const QUEST_ACTION_VALUES = [
   QUEST_ACTIONS.clear,
   QUEST_ACTIONS.reorder,
   QUEST_ACTIONS.revert,
+  QUEST_ACTIONS.reparent,
+  QUEST_ACTIONS.rules,
+  QUEST_ACTIONS.skill,
+  QUEST_ACTIONS.split,
+  QUEST_ACTIONS.add_step,
 ] as const;
 
 export type QuestActionType = (typeof QUEST_ACTION_VALUES)[number];
@@ -33,6 +43,6 @@ export interface Quest {
   createdAt: number;
 }
 
-export interface SubQuest extends Quest {
+export interface Step extends Quest {
   parentId: string;
 }

package/src/renderers/commands.ts

@@ -3,7 +3,7 @@ import { Key, matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi
 import type { ResolvedConfig } from "../config.js";
 import { logger } from "../logger.js";
 import type { QuestLog } from "../quest/dataplane.js";
-import { formatQuestRow, formatSubQuestSpacerLine } from "./quests.js";
+import { formatQuestRow, formatStepSpacerLine } from "./quests.js";
 
 export class QuestListWidget {
   private cachedWidth?: number;
@@ -50,17 +50,17 @@ export class QuestListWidget {
 
     for (let i = 0; i < parents.length; i++) {
       const parent = parents[i];
-      const subs = this.questLog.getSubQuests(parent.id);
+      const steps = this.questLog.getSteps(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));
+      if (steps.length > 0) {
+        lines.push(formatStepSpacerLine(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);
+        for (const step of steps) {
+          const stepRow = formatQuestRow(th, step, this.config.ids.length);
+          lines.push(width > 0 ? truncateToWidth(stepRow, width) : stepRow);
         }
 
         lines.push("");

package/src/renderers/quests.ts

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

package/src/renderers/tools.ts

@@ -4,7 +4,7 @@ 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";
+import { formatQuestRow, formatStepSpacerLine } from "./quests.js";
 
 type QuestArgs = {
   action: string;
@@ -76,7 +76,7 @@ export function renderQuestResult(config: ResolvedConfig) {
     const parents = quests.filter((q) => !(q as Quest & { parentId?: string }).parentId);
     const lines: string[] = [];
 
-    function getSubQuests(parentId: string) {
+    function getSteps(parentId: string) {
       return quests.filter((q) => (q as Quest & { parentId?: string }).parentId === parentId);
     }
 
@@ -85,8 +85,8 @@ export function renderQuestResult(config: ResolvedConfig) {
         const p = parents[j];
         if (renderedIds.has(p.id)) return true;
 
-        const subs = getSubQuests(p.id).filter((sq) => renderedIds.has(sq.id));
-        if (subs.length > 0) return true;
+        const steps = getSteps(p.id).filter((step) => renderedIds.has(step.id));
+        if (steps.length > 0) return true;
       }
 
       return false;
@@ -95,20 +95,20 @@ export function renderQuestResult(config: ResolvedConfig) {
     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));
+      const includedSteps = getSteps(parent.id).filter((step) => renderedIds.has(step.id));
 
-      if (!parentIncluded && includedSubs.length === 0) continue;
+      if (!parentIncluded && includedSteps.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));
+        if (includedSteps.length > 0) lines.push(formatStepSpacerLine(theme, config.ids.length));
       }
 
-      for (const sub of includedSubs) {
-        lines.push(formatQuestRow(theme, sub, config.ids.length));
+      for (const step of includedSteps) {
+        lines.push(formatQuestRow(theme, step, config.ids.length));
       }
 
-      if (includedSubs.length > 0 && willRenderLater(i)) {
+      if (includedSteps.length > 0 && willRenderLater(i)) {
         lines.push("");
       }
     }

package/src/tools/handler.ts

@@ -5,6 +5,15 @@ 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";
+
+const SPLIT_DISPLAY_ACTIONS = [
+  QUEST_ACTIONS.add,
+  QUEST_ACTIONS.list,
+  QUEST_ACTIONS.split,
+  QUEST_ACTIONS.add_step,
+  QUEST_ACTIONS.revert,
+] as const;
+
 import { renderQuestCall, renderQuestResult } from "../renderers/tools.js";
 import { createQuestParams, type QuestParamsType } from "./params.js";
 
@@ -21,7 +30,20 @@ const toolHandlers: {
     return runTool(questLog, toolCallId, {
       type: QUEST_ACTIONS.add,
       descriptions: params.descriptions,
-      parentId: params.parentId,
+    });
+  },
+  [QUEST_ACTIONS.split](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.split,
+      id: params.id,
+      descriptions: params.descriptions,
+    });
+  },
+  [QUEST_ACTIONS.add_step](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.add_step,
+      id: params.id,
+      descriptions: params.descriptions,
     });
   },
   [QUEST_ACTIONS.list](questLog, _params, toolCallId) {
@@ -50,6 +72,19 @@ const toolHandlers: {
       targetId: params.targetId,
     });
   },
+  [QUEST_ACTIONS.reparent](questLog, params, toolCallId) {
+    return runTool(questLog, toolCallId, {
+      type: QUEST_ACTIONS.reparent,
+      id: params.id,
+      parentId: params.parentId,
+    });
+  },
+  [QUEST_ACTIONS.rules](questLog, _params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.rules });
+  },
+  [QUEST_ACTIONS.skill](questLog, _params, toolCallId) {
+    return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.skill });
+  },
   [QUEST_ACTIONS.revert](questLog, _params, toolCallId) {
     return runTool(questLog, toolCallId, { type: QUEST_ACTIONS.revert });
   },
@@ -63,14 +98,13 @@ function runTool(
   const result = questLog.execute(action);
   logger.debug("quests:tool", "execute-complete", { toolCallId, success: result.success });
 
-  const displayQuests =
-    action.type === QUEST_ACTIONS.add ||
-    action.type === QUEST_ACTIONS.list ||
-    action.type === QUEST_ACTIONS.revert
-      ? questLog.getAll()
-      : result.quest
-        ? [result.quest]
-        : undefined;
+  const displayQuests = SPLIT_DISPLAY_ACTIONS.includes(
+    action.type as (typeof SPLIT_DISPLAY_ACTIONS)[number],
+  )
+    ? questLog.getAll()
+    : result.quest
+      ? [result.quest]
+      : undefined;
 
   return makeToolResult(result.message, questLog, displayQuests);
 }
@@ -95,9 +129,11 @@ export function registerQuestTool(
     name: "quest",
     label: "Quest",
     description:
-      "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.",
+      "Manage the session quest log and retrieve the complete quest system documentation. " +
+      "Use this VERY frequently to track tasks, plans, and progress. " +
+      "When you need to understand quests, steps, rules, or best practices, use action: 'skill' or action: 'rules'.",
     promptSnippet:
-      "Add (with optional parentId for sub-quests), list, toggle, update, delete, clear, or revert quest items",
+      "Manage quests and steps, or retrieve quest rules and best practices via skill/rules",
     promptGuidelines: [...QUEST_PROMPT_GATE, ...QUEST_PROMPT_REMINDER],
     parameters: createQuestParams(config.ids.length),
     execute: (toolCallId, params, _signal, _onUpdate, _ctx) =>

package/src/tools/params.ts

@@ -18,13 +18,7 @@ export function createQuestParams(idLength: number) {
         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,
@@ -38,6 +32,12 @@ export function createQuestParams(idLength: number) {
           "Target quest ID for reorder action. The quest will be moved to just before the target quest.",
       }),
     ),
+    parentId: Type.Optional(
+      Type.String({
+        pattern,
+        description: "Parent quest ID for reparent action. Omit to promote to top-level.",
+      }),
+    ),
     all: Type.Optional(
       Type.Boolean({
         description: "Clear all quests when true (defaults to clearing only completed quests)",