quest-loop 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -6,6 +6,25 @@ All notable changes to this project are documented here. The format follows
 
 ## Unreleased
 
+## [0.3.4] — 2026-07-08
+
+### Changed
+- `quest codex install-agents` and `quest claude install-agents` now allow
+  `--force` to write through symlinked agent template files, while continuing to
+  refuse symlinked provider agent directories.
+
+### Added
+- Added a Quest plan-exit reminder hook that nudges accepted `$quest:plan`
+  handoffs toward `$quest:orchestrate` rather than direct implementation.
+
+## [0.3.3] — 2026-07-08
+
+### Changed
+- `$quest:plan` now makes the planning parent session adopt
+  `$quest:orchestrate` by default after creating and linting quests, stopping
+  before dispatch only when the user explicitly asks for create-only or
+  no-dispatch behavior.
+
 ## [0.3.2] — 2026-07-08
 
 ### Added

package/README.md

@@ -22,8 +22,8 @@ actually read.
 ```
 you:    $quest:plan add dark mode to the settings page
 agent:  creates quest 12 — Objective, Done-when, Validation loop… (quest create)
-you:    $quest:orchestrate
-agent:  dispatches a worker on quest 12; it iterates: milestone → validate →
+agent:  becomes $quest:orchestrate and dispatches a worker on quest 12:
+        milestone → validate →
         commit → checkpoint. You review evidence, not vibes.
 ```
 
@@ -151,6 +151,10 @@ existing project agent template would be replaced, init fails before creating
 command with `--force` only if you intend to replace them, then rerun
 `quest init`.
 
+Agent template files may be symlinks; when you use `--force`, the install writes
+through those file symlinks. Keep `.codex/agents` and `.claude/agents` as real
+directories rather than symlinking the whole directory.
+
 Project-scoped agent templates install at the Git repository root. For a nested
 quest store, run `quest init --no-agents` in the nested directory and set
 `QUEST_DIR` for agents launched from elsewhere, or initialize from the repo root.
@@ -187,11 +191,11 @@ required:
 quest-run 12 --worker codex --codex-goal-mode require
 ```
 
-When a `$quest:plan` result is accepted from Plan Mode, the parent agent should
-stay the orchestrator: create/lint quest records if needed, set the wave goal,
-spawn subagents, verify checkpoints, and rule on reviewer findings. Product
-implementation belongs to the spawned executor for each quest, not to the parent
-session via `$quest:work`.
+When a `$quest:plan` result is accepted from Plan Mode, the parent agent
+automatically stays the orchestrator: create/lint quest records if needed, set
+the wave goal, spawn subagents, verify checkpoints, and rule on reviewer
+findings. Product implementation belongs to the spawned executor for each quest,
+not to the parent session via `$quest:work`.
 
 Each iteration ends by recording evidence — a checkpoint a fresh session can
 resume from:

package/hooks/hooks.json

@@ -62,6 +62,33 @@
           }
         ]
       }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/plan-exit-reminder.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Preparing quest orchestration reminder"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "root=\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}\"; [ -n \"$root\" ] && node \"$root/hooks/plan-exit-reminder.mjs\"",
+            "commandWindows": "if defined CODEX_PLUGIN_ROOT (node \"%CODEX_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\") else if defined CLAUDE_PLUGIN_ROOT (node \"%CLAUDE_PLUGIN_ROOT%\\hooks\\plan-exit-reminder.mjs\")",
+            "timeout": 10,
+            "statusMessage": "Checking quest plan handoff"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/plan-exit-reminder.mjs

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// Plan-exit reminder hook. When a Quest-generated plan handoff is accepted,
+// remind the parent session that the next run is orchestration, not direct
+// implementation. Anything uncertain is a silent no-op.
+
+import { writeSync } from "node:fs";
+
+const REMINDER = [
+  "Quest plan handoff accepted.",
+  "This run is about orchestration, not direct implementation:",
+  "create or confirm the quest records, run `quest lint`, then switch to `$quest:orchestrate` to dispatch workers, verify checkpoints, and close the wave.",
+].join(" ");
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+function hookEventName(payload) {
+  return payload?.hook_event_name ?? payload?.hookEventName ?? "";
+}
+
+function toolName(payload) {
+  return payload?.tool_name ?? payload?.toolName ?? payload?.tool?.name ?? "";
+}
+
+function lastAssistantMessage(payload) {
+  const value = payload?.last_assistant_message ?? payload?.lastAssistantMessage;
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") return JSON.stringify(value);
+  return "";
+}
+
+function questPlanHandoff(text) {
+  if (!text) return false;
+  const hasQuestPlan = /(?:\$?quest:plan\b|\bquest create\b|\bquest lint\b|<proposed_plan>)/i.test(text);
+  const hasOrchestrate = /(?:\$?quest:orchestrate\b|\borchestration\b|\borchestrator\b)/i.test(text);
+  return hasQuestPlan && hasOrchestrate;
+}
+
+function postToolUseText(payload) {
+  const parts = [];
+  for (const key of ["tool_input", "toolInput", "tool_response", "toolResponse"]) {
+    const value = payload?.[key];
+    if (typeof value === "string") parts.push(value);
+    else if (value && typeof value === "object") parts.push(JSON.stringify(value));
+  }
+  return parts.join("\n");
+}
+
+function shouldRemind(payload) {
+  const event = hookEventName(payload);
+  if (event === "PostToolUse" && toolName(payload) === "ExitPlanMode") {
+    return questPlanHandoff(postToolUseText(payload));
+  }
+  if (event === "Stop") {
+    return questPlanHandoff(lastAssistantMessage(payload));
+  }
+  return false;
+}
+
+try {
+  const raw = await readStdin();
+  let payload = {};
+  try { payload = raw.trim() ? JSON.parse(raw) : {}; } catch { payload = {}; }
+  if (shouldRemind(payload)) writeSync(1, JSON.stringify({ systemMessage: REMINDER }) + "\n");
+  process.exit(0);
+} catch {
+  process.exit(0);
+}

package/lib/cli.mjs

@@ -136,9 +136,9 @@ async function runNativeSetupCommand(command, args, { out, cwd, env }, { label,
     // A real run refuses to overwrite; a --dry-run PREVIEWS the conflict
     // (its whole purpose) rather than erroring before showing the plan.
     if (!result.ok && !isDry) {
-      const symlinkConflicts = result.conflicts.filter((c) => c.reason === "symlink");
-      if (symlinkConflicts.length) {
-        throw new UsageError(`refusing to write agent templates through symlinked path: ${symlinkConflicts.map((c) => c.path).join(", ")}`, { command });
+      const symlinkDirConflicts = result.conflicts.filter((c) => c.reason === "symlink-directory");
+      if (symlinkDirConflicts.length) {
+        throw new UsageError(`refusing to write agent templates through symlinked directory: ${symlinkDirConflicts.map((c) => c.path).join(", ")}`, { command });
       }
       const conflicts = result.conflicts.map((c) => c.path).join(", ");
       throw new UsageError(`agent file already exists; pass --force to replace: ${conflicts}`, { command });
@@ -147,7 +147,12 @@ async function runNativeSetupCommand(command, args, { out, cwd, env }, { label,
     else {
       out(`${isDry ? "Would install" : "Installed"} ${label} agents to ${result.target}`);
       for (const a of result.actions) out(`  ${a.action.padEnd(9)} ${a.path}`);
-      if (!result.ok) out(`  conflicts present — pass --force to replace: ${result.conflicts.map((c) => c.path).join(", ")}`);
+      if (!result.ok) {
+        const symlinkDirConflicts = result.conflicts.filter((c) => c.reason === "symlink-directory");
+        if (symlinkDirConflicts.length) out(`  symlinked directories must be real directories: ${symlinkDirConflicts.map((c) => c.path).join(", ")}`);
+        const fileConflicts = result.conflicts.filter((c) => c.reason !== "symlink-directory");
+        if (fileConflicts.length) out(`  conflicts present — pass --force to replace: ${fileConflicts.map((c) => c.path).join(", ")}`);
+      }
     }
     return 0;
   }

package/lib/codex-native.mjs

@@ -82,7 +82,6 @@ function installedAgentDirs(provider, cwd, env) {
 
 function sameFile(path, text) {
   try {
-    if (lstatSync(path).isSymbolicLink()) return false;
     return readFileSync(path, "utf8") === text;
   } catch {
     return false;
@@ -166,8 +165,8 @@ function installProviderAgents(provider, { scope = "project", dryRun = false, fo
   const dir = targetDir(provider, scope, cwd, env);
   const dirConflicts = [dirname(dir), dir]
     .filter((path, index, all) => all.indexOf(path) === index)
-    .filter((path) => existsSync(path) && isSymlink(path))
-    .map((path) => ({ name: null, path, reason: "symlink" }));
+    .filter((path) => isSymlink(path))
+    .map((path) => ({ name: null, path, reason: "symlink-directory" }));
 
   // Plan every agent first; only touch disk once the whole set is known to be
   // conflict-free. A mixed create+conflict run must not leave a partial install.
@@ -175,29 +174,25 @@ function installProviderAgents(provider, { scope = "project", dryRun = false, fo
     const src = join(PLUGIN_ROOT, "agents", `${name}.${cfg.extension}`);
     const dest = join(dir, `${name}.${cfg.extension}`);
     const text = readFileSync(src, "utf8");
-    const exists = existsSync(dest);
-    const symlink = exists && isSymlink(dest);
+    const exists = existsSync(dest) || isSymlink(dest);
     let action;
-    if (symlink) action = "conflict";
-    else if (exists && sameFile(dest, text)) action = "unchanged";
+    if (exists && sameFile(dest, text)) action = "unchanged";
     else if (exists && !force) action = "conflict";
     else action = exists ? "replace" : "create";
-    return { name, path: dest, action, text, reason: symlink ? "symlink" : undefined };
+    return { name, path: dest, action, text };
   });
 
   const conflicts = [
     ...dirConflicts,
-    ...plans.filter((p) => p.action === "conflict").map(({ name, path, reason }) => ({ name, path, ...(reason ? { reason } : {}) })),
+    ...plans.filter((p) => p.action === "conflict").map(({ name, path }) => ({ name, path })),
   ];
   const actions = plans.map(({ name, path, action }) => ({ name, path, action }));
   const ok = conflicts.length === 0;
 
   if (ok && !dryRun) {
-    if (dirConflicts.length) throw new Error(`refusing to write agent templates through symlinked path: ${dirConflicts.map((c) => c.path).join(", ")}`);
     for (const p of plans) {
       if (p.action === "unchanged") continue;
       mkdirSync(dir, { recursive: true });
-      if (isSymlink(dirname(p.path)) || isSymlink(p.path)) throw new Error(`refusing to write agent template through symlinked path: ${p.path}`);
       writeFileSync(p.path, p.text);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quest-loop",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Goal-loop engineering for coding agents: quest contracts, iterative execution with evidence checkpoints, Claude + Codex workers. Ships the `quest` store CLI and the `quest-run` headless runner.",
   "type": "module",
   "engines": { "node": ">=20" },

package/skills/plan/SKILL.md

@@ -25,18 +25,19 @@ extra context.
 ## Plan Mode handoff
 
 In Codex Plan Mode, do **not** implement product code after the user accepts a
-plan. Your role is to make the quest records real, then ask before orchestration:
+plan. The same parent agent/session that processes `$quest:plan` owns the
+handoff: make the quest records real, then adopt `$quest:orchestrate` by
+default.
 
 1. Create or confirm the quest records with `quest create` and `quest lint`.
-2. If the user accepted a plan and asked to implement it, your next role is
-   `$quest:orchestrate`, not `$quest:work`. Do not start editing product code in
-   the parent session.
-3. If the user only asked to create quests, ask whether to enter
-   `$quest:orchestrate` and dispatch the ready quests now. Do not silently
-   switch modes.
-4. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
-   goal-mode workers. If the user declines orchestration, stop after listing the
-   ready quest ids and validation commands.
+2. If the user accepted a plan and asked to implement it, the same parent
+   session becomes `$quest:orchestrate`, not `$quest:work`. Do not start editing
+   product code in the parent session.
+3. In `$quest:orchestrate`, set the orchestrator goal for the wave, then spawn
+   goal-mode workers.
+4. Stop after listing the ready quest ids and validation commands only when the
+   user explicitly asked for create-only/no-dispatch behavior such as "only
+   create quests", "do not dispatch", or "stop after planning".
 
 The parent session owns dispatch, checkpoint verification, reviewer rulings, and
 epic closure. The spawned executor owns implementation for exactly one quest.

package/skills/setup/SKILL.md

@@ -71,7 +71,8 @@ quest claude install-agents --scope user
 
 If an existing file conflicts, inspect it first. Use `--force` only when you
 intend to replace that custom agent with Quest's bundled definition. Symlinked
-agent directories or files are refused rather than overwritten.
+agent template files can be written through with `--force`; keep the provider
+agent directories themselves as real directories.
 
 ## Update Installed Plugin