quest-loop 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -6,6 +6,17 @@ 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

package/README.md

@@ -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.

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.3",
+  "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/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