openhermes 4.12.1 → 4.13.0

package/CONTEXT.md

@@ -1,12 +1,12 @@
 # OpenHermes — Shared Language
 
 ## Terms
-**OpenHermes** — OpenCode-native orchestration layer for this package.
-**Skill** — A `SKILL.md` loaded on demand through OpenCode's skill tool.
-**Command** — A slash command backed by package-local command markdown; legacy compatibility loaders remain only where runtime-backed.
-**Agent** — A primary or subagent definition loaded through OpenCode config.
-**Instruction** — Markdown loaded through `AGENTS.md` or `opencode.json` instructions.
-**Bootstrap** — The first-message context injected by the OpenHermes plugin.
+**OpenHermes** — OpenCode-native orchestration layer for this package.
+**Skill** — A `SKILL.md` loaded on demand through OpenCode's skill tool.
+**Command** — A slash command backed by package-local command markdown; legacy compatibility loaders remain only where runtime-backed.
+**Agent** — A primary or subagent definition loaded through OpenCode config.
+**Instruction** — Markdown loaded through `AGENTS.md` or `opencode.json` instructions.
+**Bootstrap** — The first-message context injected by the OpenHermes plugin.
 
 ### Confidence Gate Terms
 **Confidence Gate** — Phase 0.5 protocol in the autopilot loop that evaluates signal strength before routing. Bounded to 1 conversational exchange max.

package/ETHOS.md

@@ -8,8 +8,8 @@ OpenCode-native loading over manual copying or hidden state.
 ## Small Surface
 Every file earns its keep. Prefer markdown when behavior is declarative.
 
-## Skills Over Glue
-Behavior lives in `SKILL.md`, command markdown, and agent markdown. Legacy command-doc compatibility loaders remain supported only where runtime-backed.
+## Skills Over Glue
+Behavior lives in `SKILL.md`, command markdown, and agent markdown. Legacy command-doc compatibility loaders remain supported only where runtime-backed.
 
 ## Always Delegate — Never Execute
 OpenHermes orchestrates and reports. Sub-agents execute. OpenHermes never writes code, runs tests, or touches files directly.

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/openhermes"><img src="https://img.shields.io/npm/v/openhermes?style=for-the-badge&label=version&color=FFD700" alt="v4.11.3"></a>
+  <a href="https://www.npmjs.com/package/openhermes"><img src="https://img.shields.io/npm/v/openhermes?style=for-the-badge&label=version&color=FFD700" alt="npm version"></a>
   <a href="https://github.com/nathwn12/openhermes/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License: MIT"></a>
   <a href="https://opencode.ai"><img src="https://img.shields.io/badge/runs%20on-OpenCode-6366f1?style=for-the-badge" alt="Runs on OpenCode"></a>
   <a href="https://github.com/nathwn12/openhermes"><img src="https://img.shields.io/badge/⭐%20star%20on-GitHub-181717?style=for-the-badge" alt="Star on GitHub"></a>
@@ -33,17 +33,12 @@ To install from `dev` (latest features, may be unstable):
 
 ## One sentence. One engine.
 
-OpenHermes v4.11 ships with a hardened internal architecture — 8 subsystems working together to make every session faster, more reliable, and fully autonomous:
+OpenHermes ships with a focused internal architecture — 3 subsystems working together to make every session faster, more reliable, and fully autonomous:
 
 | Subsystem | What it does |
 |-----------|-------------|
 | **Prompt Composer** | 9 modular fragments joined at runtime → byte-identical. Add a fragment, never edit the composition code. |
-| **Auto-Recovery** | 9 error categories with typed actions — retry with backoff, compact on overflow, escalate on unknowns. Self-healing. |
-| **4-Tier Memory** | System → Project → Mission → Task. Importance-scored, budget-enforced, plan-file-persisted. Context that survives hops. |
-| **Hook Registry** | Pluggable pre-tool, post-tool, route, and session hooks with topological sort. 8 built-in hooks, zero routing boilerplate. |
-| **MVCC Sync** | Atomic writes, version counters, conflict detection. Multiple sub-agents writing the same plan file — no data loss. |
-| **Sanity Checker** | 8 output degeneration detectors — repetition, gibberish, low diversity — with automatic escalation and recovery injection. |
-| **Background Cmd** | Fire-and-forget process spawning with timeout, status polling, and auto-cleanup. Non-blocking long-running tasks. |
+| **Hook Registry** | Pluggable pre-tool, post-tool, route, and session hooks with priority-sort ordering. 7 built-in hooks, zero routing boilerplate. |
 | **Plan Location** | Resolves plan file paths per project with directory-per-project layout in `~/.local/share/openhermes/plans/`. |
 
 ---
@@ -72,11 +67,11 @@ The loop runs unsupervised because these never turn off:
 |---|---|
 | **Self-driving loop** | Type once. OpenHermes classifies, delegates, and routes — no pauses, no asking permission, no verbosity. |
 | **30 specialist skills** | Planning → building → testing → browser → security → review → shipping → retro. Every dev cycle phase. |
-| **Auto-detected user skills** | Drop a skill in `~/.agents/skills/` or `~/.config/opencode/skills/`. OpenHermes finds it. Same name as a built-in? Your version wins. Survives `npm update`. |
+| **Auto-detected user skills** | Drop a skill in `~/.agents/skills/` or `~/.config/opencode/skills/`. OpenHermes finds it. Same name as a built-in? Your version wins. Survives `npm update`. |
 | **Shared operating model** | CHARTER + AUTOPILOT + CONTEXT + ETHOS injected every session. Every interaction grounded in the same rules. |
 | **CORE/DEEP skill format** | Every skill is a two-file system: CORE (SKILL.md) handles 80% of passes in one read. DEEP.md loads on demand for hard cases. |
 | **Plan file storage** | `~/.local/share/openhermes/plans/`. Survives `npm update`. |
-| **8 internal subsystems** | Composer, recovery, memory, sync, hooks, plans, sanity, background — all native Node.js / TypeScript. |
+| **3 internal subsystems** | Composer, hooks, plans — all native Node.js / TypeScript. |
 | **Zero npm dependency additions** | All new subsystems use native Node.js and TypeScript only. No new packages. |
 
 ## 30 skills — four tiers
@@ -138,22 +133,21 @@ openhermes-pkg/
 ├── AGENTS.md              # User-side routing overlay
 ├── CONTEXT.md             # Shared domain language
 ├── ETHOS.md               # Operating principles
+├── docs/
+│   ├── HOW-IT-WORKS.md     # Runtime data flow (routing, hooks, plans)
+│   └── adr/                 # Architecture Decision Records
 ├── bootstrap.ts           # Plugin entry — registers everything
 ├── index.ts               # Package entrypoint
 ├── harness/
 │   ├── agents/            # Agent manifests (OpenHermes primary)
 │   ├── codex/             # CHARTER, AUTOPILOT
-│   ├── instructions/      # SHELL.md
+│   ├── instructions/      # SHELL.md
 │   ├── lib/               # Internal subsystems
 │   │   ├── composer/      # Prompt fragment composition
-│   │   ├── recovery/      # Auto-recovery with error patterns
-│   │   ├── memory/        # 4-tier hierarchical memory
-│   │   ├── sync/          # MVCC plan synchronization
 │   │   ├── hooks/         # Pluggable hook registry
 │   │   ├── plans/         # Plan file path resolution
-│   │   ├── sanity/        # Output degeneration detection
-│   │   └── background/    # Fire-and-forget command system
-│   └── skills/            # 30 skill SKILL.md files (CORE/DEEP format)
+│   │   └── ...            # guards/ (guard config)
+│   └── skills/            # 30 skill SKILL.md files (CORE/DEEP format)
 ├── lib/                   # harness-resolver.ts
 └── test/
     └── harness/           # Test utilities (fixture, builders, mocks)

package/bootstrap.ts

@@ -1,32 +1,27 @@
-import path from "node:path"
-import fs from "node:fs"
-import os from "node:os"
-import type { Plugin } from "@opencode-ai/plugin"
-import { getHarnessDir, setHarnessRootForTest, resolveHarnessRoot } from "./lib/harness-resolver.ts"
-import { compose } from "./harness/lib/composer/index.ts"
-import { ensurePlanFile, findLatestPlanFile, planStorageDir, setPlanStorageDirForTest, resolvePlanAccess } from "./harness/lib/plans/plan-location.ts"
-import { clearRuntimeRouteDecision, consumeRouteGuidance, getRuntimeRouteDecision, rememberRuntimeRouteDecision } from "./harness/lib/routing/index.ts"
+import path from "node:path"
+import fs from "node:fs"
+import os from "node:os"
+import type { Plugin } from "@opencode-ai/plugin"
+import { getHarnessDir, setHarnessRootForTest, resolveHarnessRoot } from "./lib/harness-resolver.ts"
+import { compose } from "./harness/lib/composer/index.ts"
+import { ensurePlanFile, findLatestPlanFile, planStorageDir, setPlanStorageDirForTest, resolvePlanAccess } from "./harness/lib/plans/plan-location.ts"
+import { clearRuntimeRouteDecision, consumeRouteGuidance, getRuntimeRouteDecision, rememberRuntimeRouteDecision } from "./harness/lib/routing/index.ts"
 
 // Hook system — pluggable lifecycle hooks with topological sort
 import {
-  HookRegistry,
-  HookResult,
-  nextRouteHook,
-  planCheckHook,
+  HookRegistry,
+  HookResult,
+  nextRouteHook,
+  planCheckHook,
   shellDetectHook,
   confidenceGateHook,
   delegationDepthHook,
   resetDepthTracker,
-  errorRecoveryHook,
-  memorySyncHook,
-  sanityCheckHook,
-  dynamicRouteHook,
-  routeTrackingHook,
-  subagentFailureHook,
-  resetSubagentFailures,
+  dynamicRouteHook,
+  routeTrackingHook,
   DEFAULT_GUARD_CONFIG,
 } from "./harness/lib/hooks/index.ts"
-import type { HookContext } from "./harness/lib/hooks/index.ts"
+import type { HookContext } from "./harness/lib/hooks/index.ts"
 
 const OPENHERMES_AGENT = "OpenHermes"
 
@@ -37,7 +32,7 @@ const USER_SKILL_DIRS: ReadonlyArray<string> = [
   path.join(os.homedir(), ".claude", "skills"),      // Claude Code backward compat
 ]
 
-export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir, ensurePlanFile, findLatestPlanFile, setPlanStorageDirForTest }
+export { resolveHarnessRoot, setHarnessRootForTest, getHarnessDir, ensurePlanFile, findLatestPlanFile, setPlanStorageDirForTest }
 
 function parseFrontmatter(raw: string | undefined): Record<string, string> {
   const frontmatter: Record<string, string> = {}
@@ -52,12 +47,12 @@ function parseFrontmatter(raw: string | undefined): Record<string, string> {
   return frontmatter
 }
 
-interface MarkdownDocument {
-  frontmatter: Record<string, string>
-  body: string
-}
-
-function readMarkdownDocument(filePath: string): MarkdownDocument | null {
+interface MarkdownDocument {
+  frontmatter: Record<string, string>
+  body: string
+}
+
+function readMarkdownDocument(filePath: string): MarkdownDocument | null {
   if (!fs.existsSync(filePath)) return null
   const source = fs.readFileSync(filePath, "utf8")
   const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/)
@@ -83,7 +78,7 @@ function readMarkdownDirectory(dir: string): DirEntry[] {
     .filter((e): e is DirEntry => e !== null)
 }
 
-interface CommandDef {
+interface CommandDef {
   description: string
   template: string
   agent?: string
@@ -106,7 +101,7 @@ function commandDefinitions(dir: string): Record<string, CommandDef> {
   return commands
 }
 
-interface AgentDef {
+interface AgentDef {
   description: string
   mode: string
   prompt: string
@@ -137,7 +132,7 @@ function uniqueStrings(existing: string[] = [], additions: string[] = []): strin
 }
 
 
-function ensureDir(dir: string): void {
+function ensureDir(dir: string): void {
   try {
     if (!fs.existsSync(dir)) {
       fs.mkdirSync(dir, { recursive: true })
@@ -149,15 +144,15 @@ function ensureDir(dir: string): void {
   }
 }
 
-export function buildCompactionContext(projectDir: string): string[] {
+export function buildCompactionContext(projectDir: string): string[] {
   const context = [
     "OpenHermes: native-first, verify before claim, always delegate, concise over verbose.",
     "Preserve domain terms: skill, command, agent, bootstrap, compaction.",
     "Preserve blockers, current task, and next steps; do not invent durable state.",
   ]
 
-  const planSummary = resolvePlanAccess(projectDir)?.summary
-  if (planSummary) context.push(planSummary)
+  const planSummary = resolvePlanAccess(projectDir)?.summary
+  if (planSummary) context.push(planSummary)
 
   return context
 }
@@ -232,7 +227,7 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
 
   return {
     config: async (config: OpenHermesConfig) => {
-
+
       // ── 1. Hooks System ─────────────────────────────────────────────────
       // Read experimental.hooks config from the raw config object
       const experimental = config.experimental as Record<string, unknown> | undefined;
@@ -244,23 +239,18 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
       if (hooksEnabled) {
         const reg = HookRegistry.getInstance()
 
-        // Check individual hook flags (default: true if not specified)
-        if (hooksConfig?.plan_check ?? true) reg.registerPreTool(planCheckHook)
-        if (hooksConfig?.shell_detect ?? true) reg.registerPreTool(shellDetectHook)
-        if (hooksConfig?.delegation_depth ?? true) reg.registerPreTool(delegationDepthHook)
-        reg.registerRoute(nextRouteHook)
-        if (hooksConfig?.confidence_gate ?? true) reg.registerRoute(confidenceGateHook)
-        if (hooksConfig?.error_recovery ?? true) reg.registerPostTool(errorRecoveryHook)
-        if (hooksConfig?.memory_sync ?? true) reg.registerPostTool(memorySyncHook)
-        if (hooksConfig?.sanity_check ?? true) reg.registerPostTool(sanityCheckHook)
-        if (hooksConfig?.dynamic_route ?? true) reg.registerPostTool(dynamicRouteHook)
-        if (hooksConfig?.route_tracking ?? true) {
-          reg.registerRoute(routeTrackingHook)
-        } else {
+        // Check individual hook flags (default: true if not specified)
+        if (hooksConfig?.plan_check ?? true) reg.registerPreTool(planCheckHook)
+        if (hooksConfig?.shell_detect ?? true) reg.registerPreTool(shellDetectHook)
+        if (hooksConfig?.delegation_depth ?? true) reg.registerPreTool(delegationDepthHook)
+        reg.registerRoute(nextRouteHook)
+        if (hooksConfig?.confidence_gate ?? true) reg.registerRoute(confidenceGateHook)
+        if (hooksConfig?.dynamic_route ?? true) reg.registerPostTool(dynamicRouteHook)
+        if (hooksConfig?.route_tracking ?? true) {
+          reg.registerRoute(routeTrackingHook)
+        } else {
           reg.unregister("route-tracking")
         }
-        if (hooksConfig?.subagent_failure ?? true) reg.registerPostTool(subagentFailureHook)
-
         await logToOC("info", `hooks: ${reg.getPreToolHooks().length + reg.getPostToolHooks().length + reg.getRouteHooks().length} registered`)
       } else {
         await logToOC("info", "hooks: disabled via config")
@@ -285,10 +275,20 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
       const loadedAgents = agentDefinitions(agentsDir)
       // Use composer for the OpenHermes agent prompt — assemble from fragments
       let openHermesPrompt: string
+      const injectSelfKnowledge = (prompt: string): string => {
+        try {
+          const pkgDir = import.meta.dirname
+          const pkg = JSON.parse(fs.readFileSync(path.resolve(pkgDir, "package.json"), "utf-8"))
+          return `OpenHermes v${pkg.version} | Install: ${pkgDir} | Harness: ${hDir}\n\n${prompt}`
+        } catch {
+          return prompt
+        }
+      }
       try {
-        openHermesPrompt = compose()
+        openHermesPrompt = injectSelfKnowledge(compose())
       } catch {
         openHermesPrompt = loadedAgents[OPENHERMES_AGENT]?.prompt ?? "You are OpenHermes."
+        openHermesPrompt = injectSelfKnowledge(openHermesPrompt)
       }
       const openHermesAgent = {
         description: loadedAgents[OPENHERMES_AGENT]?.description ?? "OpenHermes primary orchestrator",
@@ -350,11 +350,11 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
             webfetch: "allow",           // CAN fetch docs for context
             question: "allow",           // CAN ask user questions
             websearch: "allow",          // CAN search web for research context
-            external_directory: {         // CAN read/write plan files outside worktree
-              "~/.local/share/openhermes/plans/**": "allow",
-            },
-          },
-        },
+            external_directory: {         // CAN read/write plan files outside worktree
+              "~/.local/share/openhermes/plans/**": "allow",
+            },
+          },
+        },
       }
 
       config.default_agent = OPENHERMES_AGENT
@@ -370,10 +370,9 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
       // creates plans on demand (see Task Flow step 1 in agent prompt).
       // Auto-creation produced ghost skeletons like plan-004.
 
-      // Reset delegation depth and subagent failures on session start/error
+      // Reset delegation depth on session start/error
       if (typed.type === "session.created" || typed.type === "session.error") {
         resetDepthTracker()
-        resetSubagentFailures()
       }
     },
 
@@ -386,10 +385,10 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
       if (input.tool === "task") {
         const reg = HookRegistry.getInstance()
 
-        // Access optional fields from input (SDK may include these at runtime)
-        const inputAny = input as Record<string, unknown>
-        const agentName = typeof inputAny.agent === "string" ? inputAny.agent : "unknown"
-        const pendingNextRoute = getRuntimeRouteDecision(ctx.directory) ?? undefined
+        // Access optional fields from input (SDK may include these at runtime)
+        const inputAny = input as Record<string, unknown>
+        const agentName = typeof inputAny.agent === "string" ? inputAny.agent : "unknown"
+        const pendingNextRoute = getRuntimeRouteDecision(ctx.directory) ?? undefined
 
         // Build hook context from input and current session state
         const hookContext: HookContext = {
@@ -397,12 +396,12 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
           agent: agentName,
           directory: ctx.directory,
           sessions: new Map(),
-          _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
-          _confidenceExchanges: 0,
-          _guardConfig: DEFAULT_GUARD_CONFIG,
-          _nextRoute: pendingNextRoute,
-          _routingSkillsDir: skillsDir,
-        }
+          _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
+          _confidenceExchanges: 0,
+          _guardConfig: DEFAULT_GUARD_CONFIG,
+          _nextRoute: pendingNextRoute,
+          _routingSkillsDir: skillsDir,
+        }
 
         // Run all registered PreToolUse hooks (plan check, shell detect, delegation depth)
         let preToolResult: { result: HookResult; modifiedContext?: HookContext }
@@ -462,27 +461,27 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
           routeResult = { result: HookResult.CONTINUE }
         }
 
-        if (routeResult.result === HookResult.STOP) {
-          // Loop guard triggered by route-tracking hook
-          const errOutput = output as { args: unknown; isError?: boolean; content?: unknown[] }
-          errOutput.isError = true
-          const optiReport = hookContext._optiRoute
-            ? JSON.stringify(hookContext._optiRoute, null, 2)
-            : "Route guard: Excessive or unproductive routing detected."
-          errOutput.content = [{ type: "text", text: `ROUTE GUARD: ${optiReport}\n\nSurface to orchestrator with findings and stop delegating.` }]
-        }
-
-        if (routeResult.modifiedRoute) {
-          const concreteRoute = routeResult.modifiedRoute.split("?")[0] ?? routeResult.modifiedRoute
-          if (concreteRoute && concreteRoute !== agentName) {
-            inputAny.agent = concreteRoute
-          }
-          if (pendingNextRoute?.selected && concreteRoute === pendingNextRoute.selected) {
-            clearRuntimeRouteDecision(ctx.directory)
-          }
-        }
-
-        if (routeResult.result === HookResult.INJECT && routeResult.modifiedRoute) {
+        if (routeResult.result === HookResult.STOP) {
+          // Loop guard triggered by route-tracking hook
+          const errOutput = output as { args: unknown; isError?: boolean; content?: unknown[] }
+          errOutput.isError = true
+          const optiReport = hookContext._optiRoute
+            ? JSON.stringify(hookContext._optiRoute, null, 2)
+            : "Route guard: Excessive or unproductive routing detected."
+          errOutput.content = [{ type: "text", text: `ROUTE GUARD: ${optiReport}\n\nSurface to orchestrator with findings and stop delegating.` }]
+        }
+
+        if (routeResult.modifiedRoute) {
+          const concreteRoute = routeResult.modifiedRoute.split("?")[0] ?? routeResult.modifiedRoute
+          if (concreteRoute && concreteRoute !== agentName) {
+            inputAny.agent = concreteRoute
+          }
+          if (pendingNextRoute?.selected && concreteRoute === pendingNextRoute.selected) {
+            clearRuntimeRouteDecision(ctx.directory)
+          }
+        }
+
+        if (routeResult.result === HookResult.INJECT && routeResult.modifiedRoute) {
           // Confidence gate wants to inject a confirmation/pause into routing.
           // Parse the modifiedRoute for markers and inject into task description/prompt.
           const modifiedRoute: string = routeResult.modifiedRoute
@@ -520,21 +519,21 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         const agentName = typeof inputAny.agent === "string" ? inputAny.agent : "unknown"
 
         // Build hook context from input and current session state
-        const hookContext: HookContext = {
-          sessionId: ctx.directory,
-          agent: agentName,
-          directory: ctx.directory,
-          sessions: new Map(),
-          _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
-          _confidenceExchanges: 0,
-          _guardConfig: DEFAULT_GUARD_CONFIG,
-          _routingSkillsDir: skillsDir,
-        }
+        const hookContext: HookContext = {
+          sessionId: ctx.directory,
+          agent: agentName,
+          directory: ctx.directory,
+          sessions: new Map(),
+          _confidenceLevel: typeof inputAny.confidence === "string" ? inputAny.confidence : undefined,
+          _confidenceExchanges: 0,
+          _guardConfig: DEFAULT_GUARD_CONFIG,
+          _routingSkillsDir: skillsDir,
+        }
  
         // Extract output text from tool result
         // output.content may be array of content blocks, or a string, or undefined
-        const outputAny = output as Record<string, unknown> | undefined
-        const mutableOutput = (output ?? {}) as Record<string, unknown>
+        const outputAny = output as Record<string, unknown> | undefined
+        const mutableOutput = (output ?? {}) as Record<string, unknown>
         let outputText = ""
         if (outputAny?.content) {
           const content = outputAny.content
@@ -551,34 +550,27 @@ export const BootstrapPlugin: Plugin = async (ctx) => {
         try {
           const postToolResult = await reg.executePostTool(hookContext, outputText)
 
-          // Surface recovery instructions from errorRecoveryHook and/or sanityCheckHook
-          if (postToolResult.recovery) {
-            await logToOC("warn", `PostTool recovery instruction:\n${postToolResult.recovery}`)
+          // Log when hooks signal issues (INJECT = anomaly/error detected by a hook)
+          if (postToolResult.result === HookResult.INJECT) {
+            await logToOC("warn", "PostTool INJECT: hooks detected issues in tool output")
+          }
+
+          const routedOutput = consumeRouteGuidance(postToolResult.modifiedOutput ?? outputText)
+          const finalOutput = routedOutput.output
+          const runtimeNextRoute = rememberRuntimeRouteDecision(ctx.directory, finalOutput)
+
+          if (finalOutput !== outputText) {
+            if (typeof outputAny?.content === "string") {
+              mutableOutput.content = finalOutput
+            } else {
+              mutableOutput.content = [{ type: "text", text: finalOutput }]
+            }
+          }
+
+          if (runtimeNextRoute) {
+            mutableOutput._nextRoute = runtimeNextRoute
           }
 
-          // Log when hooks signal issues (INJECT = anomaly/error detected by a hook)
-          if (postToolResult.result === HookResult.INJECT) {
-            await logToOC("warn", "PostTool INJECT: hooks detected issues in tool output")
-          }
-
-          const routedOutput = consumeRouteGuidance(postToolResult.modifiedOutput ?? outputText)
-          const finalOutput = routedOutput.output
-          const runtimeNextRoute = rememberRuntimeRouteDecision(ctx.directory, finalOutput)
-
-          if (finalOutput !== outputText) {
-            if (typeof outputAny?.content === "string") {
-              mutableOutput.content = finalOutput
-            } else {
-              mutableOutput.content = [{ type: "text", text: finalOutput }]
-            }
-          }
-
-          if (runtimeNextRoute) {
-            mutableOutput._nextRoute = runtimeNextRoute
-          }
-
-          // memorySyncHook catches its own errors (best-effort sync),
-          // so memory sync failures are already handled gracefully inside the hook
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err)
           await logToOC("error", `Hook error (PostTool): ${msg}`)

package/docs/HOW-IT-WORKS.md

@@ -0,0 +1,162 @@
+# How OpenHermes Works
+
+This document traces the runtime data flow of the OpenHermes plugin package.
+It is the primary bus-factor mitigation for the routing engine, hook system, plan storage, and composer.
+
+## 1. Skill Routing Flow
+
+```
+User Request
+     │
+     ▼
+Orchestrator (classifies task, loads skill)
+     │
+     ├── Skill SKILL.md frontmatter defines routes:
+     │     pass → [oh-ship, oh-gauntlet]
+     │     fail → oh-planner
+     │     blocker → surface
+     │
+     ▼
+Route Resolver (harness/lib/routing/route-resolver.ts)
+     │
+     ├── Collects route candidates from skill frontmatter
+     ├── Applies NEXT_ROUTE overrides from subagent output
+     ├── Applies ROUTE_GUIDANCE evidence from subagent output
+     └── Selects target skill or terminal (surface/done)
+     │
+     ▼
+Dispatch to target skill subagent
+```
+
+### Key files:
+- `harness/lib/routing/route-resolver.ts` — resolves route candidates from skill frontmatter
+- `harness/lib/routing/route-guidance.ts` — applies NEXT_ROUTE overrides and evidence
+- `harness/lib/routing/skill-frontmatter.ts` — parses pass/fail/blocker from SKILL.md
+
+## 2. Hook Lifecycle
+
+```
+BootstrapPlugin registers hooks during init
+     │
+     ▼
+PreTool hooks fire before tool execution (EARLY → NORMAL → LATE)
+     │
+     ├── confidence-gate: checks user input for injection tokens
+     ├── delegation-depth: prevents runaway agent chains (max 5)
+     ├── plan-check: ensures plan files exist for multi-step work
+     └── shell-detect: identifies Windows shell type
+     │
+     ▼
+PostTool hooks fire after tool execution
+     │
+     ├── route-tracking: logs which route was taken
+     ├── next-route: captures NEXT_ROUTE from output
+     └── dynamic-route: applies evidence-driven routing
+     │
+     ▼
+Route hooks modify routing decisions
+     │
+Session hooks fire on session boundaries
+```
+
+### Hook Types:
+| Type | When | Count |
+|------|------|-------|
+| PreTool | Before each tool call | 4 |
+| PostTool | After each tool call | 3 |
+| Route | During route resolution | 0 (extensible) |
+| Session | Session start/end | 0 (extensible) |
+
+### Phases (within each hook type):
+- **EARLY** — high-priority, runs first
+- **NORMAL** — standard priority
+- **LATE** — low-priority, runs last
+
+### Key files:
+- `harness/lib/hooks/builtins/` — 7 built-in hook implementations
+- `harness/lib/hooks/hooks.test.ts` — hook system tests (928 lines)
+- `bootstrap.ts` — hook registration in `plugin.tool.execute.before/after`
+
+## 3. Plan Storage
+
+```
+Plans stored at: ~/.local/share/openhermes/plans/<project>/
+     │
+     ├── <project>/plan-001.md
+     ├── <project>/plan-002.md
+     └── <project>/plan-003.md
+     │
+     ▼
+Sequential numbering (001, 002, 003...)
+     │
+     ▼
+Status lifecycle:
+     active/in-progress → keep
+     complete/abandoned → delete
+```
+
+### Key files:
+- `harness/lib/plans/plan-location.ts` — resolves canonical paths
+- `bootstrap.ts` — exports `ensurePlanFile`, `findLatestPlanFile`, `resolveHarnessRoot`
+
+## 4. Composer (Agent Prompt Assembly)
+
+```
+9 numbered fragments in harness/lib/composer/fragments/
+     │
+     ├── 01-identity.md    → "You are OpenHermes..."
+     ├── 02-delegation.md  → Core Behaviors
+     ├── 03-permissions.md → Permission matrix
+     ├── 04-task-flow.md   → Task flow steps
+     ├── 05-confidence.md  → Stop Conditions
+     ├── 06-parallelization.md → Parallelization rules
+     ├── 07-shell.md       → Shell Awareness
+     ├── 08-routing.md     → Plan Storage
+     └── 09-guardrails.md  → Guardrails + Routing
+     │
+     ▼
+compose.ts assembles fragments with phase filtering (EARLY/NORMAL/LATE)
+     │
+     ▼
+Path traversal sanitization prevents directory escape
+     │
+     ▼
+Output: complete agent prompt consumed by the LLM
+```
+
+### Key files:
+- `harness/lib/composer/compose.ts` — fragment assembly engine
+- `harness/lib/composer/fragments/` — 9 content fragments
+- `harness/agents/openhermes.md` — agent manifest declaring fragments
+
+## 5. Full Request Lifecycle (ASCII Overview)
+
+```
+┌─────────────────────────────────────────────────────┐
+│  User sends request                                 │
+│         │                                           │
+│         ▼                                           │
+│  OpenHermes Orchestrator                            │
+│         │                                           │
+│         ├── 1. Classify task (investigate/build/...)│
+│         ├── 2. Load skill (SKILL.md frontmatter)    │
+│         ├── 3. PreTool hooks fire (confidence, etc) │
+│         ├── 4. Delegate to subagent                 │
+│         ├── 5. Subagent returns output + evidence   │
+│         ├── 6. PostTool hooks fire (tracking, etc)  │
+│         ├── 7. ROUTE_EVIDENCE parsed                │
+│         └── 8. Route to next skill or surface       │
+│                    │                                │
+│                    ▼                                │
+│  Next skill (or surface/done)                       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Architecture Summary
+
+| System | Purpose | Key File |
+|--------|---------|----------|
+| Routing | Resolves next skill from frontmatter + evidence | `harness/lib/routing/route-resolver.ts` |
+| Hooks | Plugin extensibility points | `harness/lib/hooks/builtins/` |
+| Plans | Canonical task tracking | `harness/lib/plans/plan-location.ts` |
+| Composer | Agent prompt assembly | `harness/lib/composer/compose.ts` |