openhermes 4.9.2 → 4.12.1

package/harness/lib/composer/fragments/07-shell.md

@@ -0,0 +1,41 @@
+## Confidence Gate Examples
+
+**HIGH (transparent):**
+> User: "There's a bug in the login flow"
+> Orchestrator: (no conversation) → Classifies as INVESTIGATION → Loads oh-investigate
+
+**MEDIUM (echo):**
+> User: "Clean up the codebase and make it faster"
+> Orchestrator: "I hear performance + cleanup work. Routing to oh-planner for a plan — does that match?"
+> User: "Yes" → Classifies → Delegates
+> (If "No, just run lint" → Re-analyzes → Classifies as HEALTH → Loads oh-health)
+
+**LOW (question):**
+> User: "I have an idea for the app"
+> Orchestrator: "Quick one — is this about a new feature, a redesign, or something else?"
+> User: "A new feature" → Classifies as PLANNING → Loads oh-planner
+> (No answer → Default to oh-planner)
+
+## Shell Awareness (Windows)
+
+You run on Windows. Three possible shells: CMD, PowerShell, Git Bash. Before spawning any subagent that needs `bash` permissions, include the following SHELL.md preamble in the subagent's task prompt. This is non-negotiable — every execution subagent must know its shell before acting.
+
+Subagent task preamble — prepend to every execution subagent prompt:
+~~~markdown
+## Shell Pre-flight
+Detect your shell before any command:
+- `$PSVersionTable` exists → PowerShell
+- `%CMDCMDLINE%` is set → CMD
+- `$0` or `$BASH` → Git Bash
+
+Required shell by operation:
+- file ops, scoop, ps1 scripts, env vars → PowerShell
+- git, bun, npm, node → any shell (all work)
+- rm -rf, make, unix scripts → Git Bash
+- .bat/.cmd → CMD
+
+If wrong shell:
+- → PowerShell: `powershell.exe -NoProfile -Command "..."`
+- → Git Bash: `& "C:\Program Files\Git\bin\bash.exe" -c "..."`
+- → CMD: `cmd.exe /c "..."`
+~~~

package/harness/lib/composer/fragments/08-routing.md

@@ -0,0 +1,8 @@
+## Plan Storage
+
+Canonical path: `~/.local/share/openhermes/plans/<project-name>/plan-<nnn>.md`
+
+- Plan files use `<project-name>/plan-<nnn>.md` naming — one directory per project, sequence zero-padded to 3 digits
+- Status lifecycle: keep `active`/`in-progress`/`blocked`, delete `complete`/`abandoned`
+- Entries are direct filesystem operations — no tracking DB
+- The bootstrap plugin's `ensurePlanFile()` handles creation and reuse; delegate to sub-agents when possible

package/harness/lib/composer/fragments/09-guardrails.md

@@ -0,0 +1,25 @@
+## Guardrails
+
+- All loop and safety limits are mechanically enforced by hooks (route-tracking, delegation-depth, subagent-failure). See AUTOPILOT.md §Safety Valves for limits and configuration.
+- Before routing: if next skill's required input is missing and cannot be discovered → surface
+- Concrete, low-risk findings from review or investigation are implementation candidates, not report-only endpoints; dispatch to oh-builder immediately.
+- Confidence is evaluated once per session, not per routing hop — only re-evaluate when new user input arrives
+- User skills at `~/.agents/skills/` and `~/.config/opencode/skills/` load on demand via skill tool
+- Do not ask the user to resolve something the codebase or prior conversation already resolves. Ask only for true blockers.
+- For fusion or protocol work, stop at an explicit approval gate before changing the harness. Approved plan in context counts as approval.
+- If a proposed protocol makes OH weaker, slower, noisier, or less native, call that out, revise it, and prefer the stronger path before routing onward.
+
+## Routing
+
+After every skill (in priority order):
+1. `NEXT_ROUTE: <skill>` from output — explicit override, highest priority
+2. `ROUTE_GUIDANCE.selected` from output — evidence-driven route, including richer routing signals
+3. Skill's `route:` frontmatter (pass / fail / blocker) — static fallback
+
+For multi-candidate routes (e.g., pass: [oh-gauntlet, oh-ship]), the orchestrator should emit `ROUTE_EVIDENCE:` JSON with the richer schema. The runtime resolver applies these rules:
+- verified + done + ship → prefers `oh-ship`
+- unverified → prefers `oh-gauntlet`
+- fixable / implement → prefers `oh-builder`
+- explicit target in evidence → preferred when valid
+
+Route immediately. Do not ask. Route values: `oh-<name>` (another skill), `surface`, `done` (terminal), `[a, b]` (choose with evidence). Internal switch: `mode`. If the result is a concrete, low-risk fix, do not end in a report: hand it to oh-builder.

package/harness/lib/composer/index.ts

@@ -0,0 +1 @@
+export { compose, composeFragment, listFragments } from "./compose.ts"

package/harness/lib/guards/guard-config.ts

@@ -0,0 +1,72 @@
+// ---------------------------------------------------------------------------
+// GuardConfig — centralized configuration for all loop/safety guards
+// ---------------------------------------------------------------------------
+
+export interface GuardConfig {
+  /** Max times the same skill can repeat in one chain before STOP */
+  maxSkillRepeats: number
+  /** Max consecutive unproductive hops before STOP (0 = disabled) */
+  maxUnproductiveHops: number
+  /** Max delegation (sub-agent) depth before STOP */
+  maxDelegationDepth: number
+  /** Consecutive anomalies before recovery escalation */
+  maxConsecutiveAnomalies: number
+  /** Max subagent failures on same task before BLOCKER */
+  maxSubagentFailures: number
+  /** Enable progressive warning at thresholds before hard stop */
+  progressiveGuards: boolean
+  /** Ratio of limit at which to warn (e.g. 0.6 = 60%) */
+  progressiveWarnThreshold: number
+  /** Ratio of limit at which to escalate (e.g. 0.8 = 80%) */
+  progressiveEscalateThreshold: number
+}
+
+export const DEFAULT_GUARD_CONFIG: GuardConfig = {
+  maxSkillRepeats: 5,
+  maxUnproductiveHops: 8,
+  maxDelegationDepth: 25,
+  maxConsecutiveAnomalies: 2,
+  maxSubagentFailures: 5,
+  progressiveGuards: true,
+  progressiveWarnThreshold: 0.6,
+  progressiveEscalateThreshold: 0.8,
+}
+
+export type GuardLevel = "ok" | "warn" | "escalate" | "stop"
+
+export interface GuardProgression {
+  level: GuardLevel
+  current: number
+  limit: number
+  /**
+   * If progressive guards are disabled: stop at limit, ok otherwise.
+   * If enabled: ok < warn% < escalate% < stop.
+   */
+}
+
+export function checkGuardProgression(
+  current: number,
+  limit: number,
+  config: GuardConfig,
+): GuardProgression {
+  if (!config.progressiveGuards || limit <= 0) {
+    return {
+      level: current >= limit ? "stop" as GuardLevel : "ok" as GuardLevel,
+      current,
+      limit,
+    }
+  }
+  if (current >= limit) return { level: "stop", current, limit }
+  if (current / limit >= config.progressiveEscalateThreshold) return { level: "escalate" as GuardLevel, current, limit }
+  if (current / limit >= config.progressiveWarnThreshold) return { level: "warn" as GuardLevel, current, limit }
+  return { level: "ok" as GuardLevel, current, limit }
+}
+
+/**
+ * Merge partial user config(s) with defaults.
+ * Priority: defaults → earlier args → later args (last wins).
+ * Supports single-arg calls and multi-override chains.
+ */
+export function mergeGuardConfig(...overrides: Array<Partial<GuardConfig> | undefined>): GuardConfig {
+  return Object.assign({}, DEFAULT_GUARD_CONFIG, ...overrides.filter(Boolean));
+}

package/harness/lib/hooks/builtins/confidence-gate-hook.ts

@@ -0,0 +1,68 @@
+// ---------------------------------------------------------------------------
+// ConfidenceGateHook — RouteHook, priority=70, phase=NORMAL
+//
+// Before routing, check if confidence gate needs to pause.
+// Adjust route based on confidence level.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, RouteHook } from "../types.ts";
+
+export interface ConfidenceGateState {
+  level: "HIGH" | "MEDIUM" | "LOW";
+  exchanges: number;
+  lastAction: string;
+}
+
+export const confidenceGateHook: RouteHook = {
+  metadata: {
+    name: "confidence-gate",
+    priority: 70,
+    phase: HookPhase.NORMAL,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, route: string) {
+    // Read confidence state from context if available
+    const confidenceLevel = context._confidenceLevel;
+
+    if (!confidenceLevel) {
+      // No confidence gate info — pass through unchanged
+      return { result: HookResult.CONTINUE, modifiedRoute: route };
+    }
+
+    // Store the confidence assessment for routing decisions
+    const state: ConfidenceGateState = {
+      level: confidenceLevel as ConfidenceGateState["level"],
+      exchanges: context._confidenceExchanges ?? 0,
+      lastAction: "assessed",
+    };
+
+    // HIGH confidence: proceed without modification
+    if (state.level === "HIGH") {
+      return {
+        result: HookResult.CONTINUE,
+        modifiedRoute: route,
+      };
+    }
+
+    // MEDIUM confidence: echo if first pass, otherwise proceed
+    if (state.level === "MEDIUM" && state.exchanges === 0) {
+      return {
+        result: HookResult.INJECT,
+        modifiedRoute: `${route}?echo=confirm`,
+      };
+    }
+
+    // LOW confidence: pause if first pass, otherwise proceed
+    if (state.level === "LOW" && state.exchanges === 0) {
+      return {
+        result: HookResult.INJECT,
+        modifiedRoute: `${route}?question=pause`,
+      };
+    }
+
+    return { result: HookResult.CONTINUE, modifiedRoute: route };
+  },
+};

package/harness/lib/hooks/builtins/delegation-depth-hook.ts

@@ -0,0 +1,78 @@
+// ---------------------------------------------------------------------------
+// DelegationDepthHook — PreToolUse, priority=60, phase=NORMAL
+//
+// Loop guard — track sub-agent call depth.
+// If depth exceeds max, STOP and escalate.
+// Progressive warning at thresholds before hard stop.
+//
+// Reads maxDelegationDepth from _guardConfig (centralized) with fallback
+// to _maxDelegationDepth for backward compatibility.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PreToolUseHook } from "../types.ts";
+import type { GuardConfig } from "../../guards/guard-config.ts";
+import { checkGuardProgression, DEFAULT_GUARD_CONFIG } from "../../guards/guard-config.ts";
+
+/** Module-level depth tracker — maps sessionId to current depth */
+const depthTrackers = new Map<string, number>();
+
+export function resetDepthTracker(): void {
+  depthTrackers.clear();
+}
+
+export function getDepth(sessionId: string): number {
+  return depthTrackers.get(sessionId) ?? 0;
+}
+
+export const delegationDepthHook: PreToolUseHook = {
+  metadata: {
+    name: "delegation-depth",
+    priority: 60,
+    phase: HookPhase.NORMAL,
+    dependencies: [],
+    errorHandling: "propagate",
+  },
+
+  async execute(context: HookContext) {
+    const sessionId = context.sessionId;
+
+    // Bump depth
+    const currentDepth = (depthTrackers.get(sessionId) ?? 0) + 1;
+    depthTrackers.set(sessionId, currentDepth);
+
+    // Resolve guard config for progression checks
+    const guardConfig: GuardConfig = context._guardConfig ?? DEFAULT_GUARD_CONFIG;
+
+    // Backward compat: if legacy _maxDelegationDepth is set, use it
+    // Otherwise use _guardConfig (centralized) with defaults
+    const legacyDepth = (context as any)._maxDelegationDepth as number | undefined;
+    const maxDepth = legacyDepth !== undefined ? legacyDepth : guardConfig.maxDelegationDepth;
+
+    // Progressive warning check
+    const progression = checkGuardProgression(currentDepth, maxDepth, guardConfig);
+
+    if (progression.level === "warn" || progression.level === "escalate") {
+      // Annotate context for the orchestrator but don't stop
+      context._guardProgression = progression;
+    }
+
+    if (progression.level === "stop") {
+      return {
+        result: HookResult.STOP,
+        modifiedContext: {
+          _depthExceeded: true,
+          _depthError: `LOOP GUARD: Delegation depth exceeded (max ${maxDepth}). Surface to orchestrator with findings and stop delegating.`,
+          _delegationDepth: currentDepth,
+        },
+      };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _delegationDepth: currentDepth,
+      },
+    };
+  },
+};

package/harness/lib/hooks/builtins/dynamic-route-hook.ts

@@ -0,0 +1,99 @@
+import path from "node:path";
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { readSkillFrontmatter, resolveRoute } from "../../routing/index.ts";
+import type { RouteEvidence } from "../../routing/index.ts";
+import { ROUTE_GUIDANCE_PREFIX } from "../../routing/index.ts";
+import {
+  ROUTE_ACTIONS,
+  ROUTE_OUTCOMES,
+  ROUTE_VERIFICATIONS,
+  ROUTE_WORK_TYPES,
+} from "../../routing/types.ts";
+
+const ROUTE_EVIDENCE_PREFIX = "ROUTE_EVIDENCE:";
+
+function isRouteOutcome(value: unknown): value is RouteEvidence["outcome"] {
+  return typeof value === "string" && ROUTE_OUTCOMES.includes(value as RouteEvidence["outcome"]);
+}
+
+function isRouteVerification(value: unknown): value is NonNullable<RouteEvidence["verification"]> {
+  return typeof value === "string" && ROUTE_VERIFICATIONS.includes(value as NonNullable<RouteEvidence["verification"]>);
+}
+
+function isRouteAction(value: unknown): value is NonNullable<RouteEvidence["action"]> {
+  return typeof value === "string" && ROUTE_ACTIONS.includes(value as NonNullable<RouteEvidence["action"]>);
+}
+
+function isRouteWork(value: unknown): value is NonNullable<RouteEvidence["work"]> {
+  return typeof value === "string" && ROUTE_WORK_TYPES.includes(value as NonNullable<RouteEvidence["work"]>);
+}
+
+function parseRouteEvidence(output: string): RouteEvidence | null {
+  const evidenceLine = output
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => line.startsWith(ROUTE_EVIDENCE_PREFIX));
+
+  if (!evidenceLine) return null;
+
+  const raw = evidenceLine.slice(ROUTE_EVIDENCE_PREFIX.length).trim();
+  if (!raw) return null;
+
+  try {
+    const parsed = JSON.parse(raw) as Partial<RouteEvidence>;
+    if (!isRouteOutcome(parsed.outcome)) return null;
+    if (parsed.verification !== undefined && !isRouteVerification(parsed.verification)) return null;
+    if (parsed.action !== undefined && !isRouteAction(parsed.action)) return null;
+    if (parsed.work !== undefined && !isRouteWork(parsed.work)) return null;
+    if (parsed.target !== undefined && typeof parsed.target !== "string") return null;
+    if (parsed.reason !== undefined && typeof parsed.reason !== "string") return null;
+
+    return {
+      outcome: parsed.outcome,
+      ...(parsed.verification ? { verification: parsed.verification } : {}),
+      ...(parsed.action ? { action: parsed.action } : {}),
+      ...(parsed.work ? { work: parsed.work } : {}),
+      ...(parsed.target ? { target: parsed.target } : {}),
+      ...(parsed.reason ? { reason: parsed.reason } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export const dynamicRouteHook: PostToolUseHook = {
+  metadata: {
+    name: "dynamic-route",
+    priority: 20,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    const evidence = parseRouteEvidence(output);
+    const skillsDir = typeof context._routingSkillsDir === "string" ? context._routingSkillsDir : undefined;
+
+    if (!evidence || !skillsDir || !context.agent) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    const skillFilePath = path.join(skillsDir, context.agent, "SKILL.md");
+    const frontmatter = readSkillFrontmatter(skillFilePath);
+    if (!frontmatter) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    const resolution = resolveRoute(frontmatter.route, evidence);
+    const guidance = `${ROUTE_GUIDANCE_PREFIX} ${JSON.stringify(resolution)}`;
+    const modifiedOutput = output.includes(ROUTE_GUIDANCE_PREFIX)
+      ? output
+      : `${output.trimEnd()}\n${guidance}`.trim();
+
+    return {
+      result: HookResult.INJECT,
+      modifiedOutput,
+    };
+  },
+};

package/harness/lib/hooks/builtins/error-recovery-hook.ts

@@ -0,0 +1,107 @@
+// ---------------------------------------------------------------------------
+// ErrorRecoveryHook — PostToolUse, priority=50, phase=LATE
+//
+// After sub-agent call, check if output indicates error.
+// Use the RecoveryHandler to match patterns and inject recovery actions.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { RecoveryHandler } from "../../recovery/handler.ts";
+import type { ErrorContext } from "../../recovery/interfaces.ts";
+
+export const errorRecoveryHook: PostToolUseHook = {
+  metadata: {
+    name: "error-recovery",
+    priority: 50,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    // Check if the output looks like an error
+    const isErrorOutput = looksLikeError(output);
+    if (!isErrorOutput) {
+      return { result: HookResult.CONTINUE };
+    }
+
+    // Classify the error and get a recovery action
+    const handler = RecoveryHandler.getInstance();
+    const errorContext: ErrorContext = {
+      sessionId: context.sessionId,
+      error: new Error(output.slice(0, 500)), // Truncate for classification
+      attempt: context._recoveryAttempt ?? 0,
+      timestamp: Date.now(),
+      agent: context.agent,
+    };
+
+    const action = handler.handleError(errorContext);
+
+    // Build a recovery instruction based on the action
+    const recoveryInstruction = buildRecoveryInstruction(action);
+
+    return {
+      result: HookResult.INJECT,
+      modifiedOutput: output,
+      injectRecovery: recoveryInstruction,
+    };
+  },
+};
+
+/**
+ * Heuristic check: does the output look like an error?
+ * Looks for common error patterns in tool output.
+ */
+function looksLikeError(output: string): boolean {
+  if (!output || output.length === 0) return false;
+
+  const errorPatterns = [
+    /error/i,
+    /exception/i,
+    /failed/i,
+    /failure/i,
+    /unable to/i,
+    /could not/i,
+    /not found/i,
+    /ECONNREFUSED/i,
+    /ETIMEDOUT/i,
+    /rate.?limited/i,
+    /too many requests/i,
+    /context.?length/i,
+    /token.?limit/i,
+    /parse.?error/i,
+    /syntax.?error/i,
+    /timeout/i,
+    /execution.?timed.?out/i,
+  ];
+
+  // Check first 2000 chars to avoid false positives in long output
+  const head = output.slice(0, 2000);
+  return errorPatterns.some((p) => p.test(head));
+}
+
+/**
+ * Build a recovery instruction string from a RecoveryAction.
+ */
+function buildRecoveryInstruction(
+  action: { type: string; delay?: number; maxAttempts?: number; reason: string; modifyPrompt?: string },
+): string {
+  const parts: string[] = [
+    `[HOOK: Error Recovery]`,
+    `Action: ${action.type}`,
+    `Reason: ${action.reason}`,
+  ];
+
+  if (action.delay) {
+    parts.push(`Delay: ${action.delay}ms before retry`);
+  }
+  if (action.maxAttempts) {
+    parts.push(`Max attempts: ${action.maxAttempts}`);
+  }
+  if (action.modifyPrompt) {
+    parts.push(`Modification: ${action.modifyPrompt}`);
+  }
+
+  return parts.join("\n");
+}

package/harness/lib/hooks/builtins/memory-sync-hook.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// MemorySyncHook — PostToolUse, priority=40, phase=LATE
+//
+// After each step, sync memory entries to plan file.
+// Uses MemoryManager from harness/lib/memory/memory-manager.ts
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PostToolUseHook } from "../types.ts";
+import { MemoryManager } from "../../memory/memory-manager.ts";
+import { PlanStore } from "../../memory/plan-store.ts";
+import { resolvePlanAccess } from "../../plans/plan-location.ts";
+import { MemoryLevel } from "../../memory/interfaces.ts";
+
+export const memorySyncHook: PostToolUseHook = {
+  metadata: {
+    name: "memory-sync",
+    priority: 40,
+    phase: HookPhase.LATE,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, output: string) {
+    // Sync memory entries to plan file
+    const planFile = resolvePlanAccess(context.directory)?.path ?? null;
+    if (!planFile) {
+      // No plan file to sync to — skip silently
+      return { result: HookResult.CONTINUE };
+    }
+
+    const mem = MemoryManager.getInstance();
+
+    // Extract findings from the session memory (TASK level)
+    const taskEntries = mem.getEntries(MemoryLevel.TASK);
+
+    // Sync important task entries as plan findings
+    for (const entry of taskEntries) {
+      if (entry.importance >= 0.6) {
+        try {
+          await PlanStore.addFinding(planFile, context.sessionId, {
+            description: entry.content,
+            severity: entry.importance >= 0.8 ? "warning" : "info",
+          });
+        } catch {
+          // Plan sync is best-effort — don't break execution
+        }
+      }
+    }
+
+    // Sync any decisions
+    const missionEntries = mem.getEntries(MemoryLevel.MISSION);
+    for (const entry of missionEntries) {
+      if (entry.metadata?.type === "decision" && entry.importance >= 0.7) {
+        try {
+          await PlanStore.addDecision(planFile, context.sessionId, {
+            description: entry.content,
+            rationale: (entry.metadata.rationale as string) ?? "Auto-synced decision",
+          });
+        } catch {
+          // Best-effort
+        }
+      }
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _memorySyncCount: taskEntries.filter((e) => e.importance >= 0.6).length,
+      },
+    };
+  },
+};

package/harness/lib/hooks/builtins/next-route-hook.ts

@@ -0,0 +1,24 @@
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, RouteHook } from "../types.ts";
+
+export const nextRouteHook: RouteHook = {
+  metadata: {
+    name: "next-route",
+    priority: 90,
+    phase: HookPhase.EARLY,
+    dependencies: [],
+    errorHandling: "isolate",
+  },
+
+  async execute(context: HookContext, route: string) {
+    const nextRoute = context._nextRoute?.selected;
+    if (!nextRoute || nextRoute === route) {
+      return { result: HookResult.CONTINUE, modifiedRoute: route };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedRoute: nextRoute,
+    };
+  },
+};

package/harness/lib/hooks/builtins/plan-check-hook.ts

@@ -0,0 +1,43 @@
+// ---------------------------------------------------------------------------
+// PlanCheckHook — PreToolUse, priority=90, phase=EARLY
+//
+// Before any sub-agent call, verify plan file exists at the expected path.
+// If missing, inject "create plan first" instruction.
+// ---------------------------------------------------------------------------
+
+import { HookPhase, HookResult } from "../types.ts";
+import type { HookContext, PreToolUseHook } from "../types.ts";
+import { resolvePlanAccess } from "../../plans/plan-location.ts";
+
+export const planCheckHook: PreToolUseHook = {
+  metadata: {
+    name: "plan-check",
+    priority: 90,
+    phase: HookPhase.EARLY,
+    dependencies: [],
+    errorHandling: "propagate",
+  },
+
+  async execute(context: HookContext) {
+    const planFile = resolvePlanAccess(context.directory)?.path ?? null;
+
+    if (!planFile) {
+      return {
+        result: HookResult.INJECT,
+        modifiedContext: {
+          _planCheck: "missing",
+          _planCheckInstruction:
+            "No plan file found. Create a plan first before proceeding with any sub-agent tasks.",
+        },
+      };
+    }
+
+    return {
+      result: HookResult.CONTINUE,
+      modifiedContext: {
+        _planCheck: "found",
+        _planFilePath: planFile,
+      },
+    };
+  },
+};