feat(agents): add Hephaestus - autonomous deep worker agent (#1287)

* refactor(keyword-detector): split constants into domain-specific modules

* feat(shared): add requiresAnyModel and isAnyFallbackModelAvailable

* feat(config): add hephaestus to agent schemas

* feat(agents): add Hephaestus autonomous deep worker

* feat(cli): update model-fallback for hephaestus support

* feat(plugin): add hephaestus to config handler with ordering

* test(delegate-task): update tests for hephaestus agent

* docs: update AGENTS.md files for hephaestus

* docs: add hephaestus to READMEs

* chore: regenerate config schema

* fix(delegate-task): bypass requiresModel check when user provides explicit config

* docs(hephaestus): add 4-part context structure for explore/librarian prompts

* docs: fix review comments from cubic (non-breaking changes)

- Move Hephaestus from Primary Agents to Subagents (uses own fallback chain)
- Fix Hephaestus fallback chain documentation (claude-opus-4-5 → gemini-3-pro)
- Add settings.local.json to claude-code-hooks config sources
- Fix delegate_task parameters in ultrawork prompt (agent→subagent_type, background→run_in_background, add load_skills)
- Update line counts in AGENTS.md (index.ts: 788, manager.ts: 1440)

* docs: fix additional documentation inconsistencies from oracle review

- Fix delegate_task parameters in Background Agents example (docs/features.md)
- Fix Hephaestus fallback chain in root AGENTS.md to match model-requirements.ts

* docs: clarify Hephaestus has no fallback (requires gpt-5.2-codex only)

Hephaestus uses requiresModel constraint - it only activates when gpt-5.2-codex
is available. The fallback chain in code is unreachable, so documentation
should not mention fallbacks.

* fix(hephaestus): remove unreachable fallback chain entries

Hephaestus has requiresModel: gpt-5.2-codex which means the agent only
activates when that specific model is available. The fallback entries
(claude-opus-4-5, gemini-3-pro) were unreachable and misleading.

---------

Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com>

src/agents/utils.ts

@@ -9,8 +9,9 @@ import { createMultimodalLookerAgent, MULTIMODAL_LOOKER_PROMPT_METADATA } from "
 import { createMetisAgent, metisPromptMetadata } from "./metis"
 import { createAtlasAgent, atlasPromptMetadata } from "./atlas"
 import { createMomusAgent, momusPromptMetadata } from "./momus"
+import { createHephaestusAgent } from "./hephaestus"
 import type { AvailableAgent, AvailableCategory, AvailableSkill } from "./dynamic-agent-prompt-builder"
-import { deepMerge, fetchAvailableModels, resolveModelPipeline, AGENT_MODEL_REQUIREMENTS, readConnectedProvidersCache, isModelAvailable } from "../shared"
+import { deepMerge, fetchAvailableModels, resolveModelPipeline, AGENT_MODEL_REQUIREMENTS, readConnectedProvidersCache, isModelAvailable, isAnyFallbackModelAvailable } from "../shared"
 import { DEFAULT_CATEGORIES, CATEGORY_DESCRIPTIONS } from "../tools/delegate-task/constants"
 import { resolveMultipleSkills } from "../features/opencode-skill-loader/skill-content"
 import { createBuiltinSkills } from "../features/builtin-skills"
@@ -21,6 +22,7 @@ type AgentSource = AgentFactory | AgentConfig
 
 const agentSources: Record<BuiltinAgentName, AgentSource> = {
   sisyphus: createSisyphusAgent,
+  hephaestus: createHephaestusAgent,
   oracle: createOracleAgent,
   librarian: createLibrarianAgent,
   explore: createExploreAgent,
@@ -260,10 +262,14 @@ export async function createBuiltinAgents(
 
   const availableSkills: AvailableSkill[] = [...builtinAvailable, ...discoveredAvailable]
 
+  // Collect general agents first (for availableAgents), but don't add to result yet
+  const pendingAgentConfigs: Map<string, AgentConfig> = new Map()
+
    for (const [name, source] of Object.entries(agentSources)) {
      const agentName = name as BuiltinAgentName
 
      if (agentName === "sisyphus") continue
+     if (agentName === "hephaestus") continue
      if (agentName === "atlas") continue
      if (disabledAgents.some((name) => name.toLowerCase() === agentName.toLowerCase())) continue
 
@@ -309,7 +315,8 @@ export async function createBuiltinAgents(
 
     config = applyOverrides(config, override, mergedCategories)
 
-    result[name] = config
+    // Store for later - will be added after sisyphus and hephaestus
+    pendingAgentConfigs.set(name, config)
 
     const metadata = agentMetadata[agentName]
     if (metadata) {
@@ -321,10 +328,15 @@ export async function createBuiltinAgents(
     }
   }
 
-   if (!disabledAgents.includes("sisyphus")) {
-     const sisyphusOverride = agentOverrides["sisyphus"]
-     const sisyphusRequirement = AGENT_MODEL_REQUIREMENTS["sisyphus"]
-    
+   const sisyphusOverride = agentOverrides["sisyphus"]
+   const sisyphusRequirement = AGENT_MODEL_REQUIREMENTS["sisyphus"]
+   const hasSisyphusExplicitConfig = sisyphusOverride !== undefined
+   const meetsSisyphusAnyModelRequirement =
+     !sisyphusRequirement?.requiresAnyModel ||
+     hasSisyphusExplicitConfig ||
+     isAnyFallbackModelAvailable(sisyphusRequirement.fallbackChain, availableModels)
+
+   if (!disabledAgents.includes("sisyphus") && meetsSisyphusAnyModelRequirement) {
     const sisyphusResolution = applyModelResolution({
       uiSelectedModel,
       userModel: sisyphusOverride?.model,
@@ -355,6 +367,61 @@ export async function createBuiltinAgents(
     }
    }
 
+  if (!disabledAgents.includes("hephaestus")) {
+    const hephaestusOverride = agentOverrides["hephaestus"]
+    const hephaestusRequirement = AGENT_MODEL_REQUIREMENTS["hephaestus"]
+    const hasHephaestusExplicitConfig = hephaestusOverride !== undefined
+
+    const hasRequiredModel =
+      !hephaestusRequirement?.requiresModel ||
+      hasHephaestusExplicitConfig ||
+      (availableModels.size > 0 && isModelAvailable(hephaestusRequirement.requiresModel, availableModels))
+
+    if (hasRequiredModel) {
+      const hephaestusResolution = applyModelResolution({
+        userModel: hephaestusOverride?.model,
+        requirement: hephaestusRequirement,
+        availableModels,
+        systemDefaultModel,
+      })
+
+      if (hephaestusResolution) {
+        const { model: hephaestusModel, variant: hephaestusResolvedVariant } = hephaestusResolution
+
+        let hephaestusConfig = createHephaestusAgent(
+          hephaestusModel,
+          availableAgents,
+          undefined,
+          availableSkills,
+          availableCategories
+        )
+        
+        hephaestusConfig = { ...hephaestusConfig, variant: hephaestusResolvedVariant ?? "medium" }
+
+        const hepOverrideCategory = (hephaestusOverride as Record<string, unknown> | undefined)?.category as string | undefined
+        if (hepOverrideCategory) {
+          hephaestusConfig = applyCategoryOverride(hephaestusConfig, hepOverrideCategory, mergedCategories)
+        }
+
+        if (directory && hephaestusConfig.prompt) {
+          const envContext = createEnvContext()
+          hephaestusConfig = { ...hephaestusConfig, prompt: hephaestusConfig.prompt + envContext }
+        }
+
+        if (hephaestusOverride) {
+          hephaestusConfig = mergeAgentConfig(hephaestusConfig, hephaestusOverride)
+        }
+
+        result["hephaestus"] = hephaestusConfig
+      }
+    }
+   }
+
+   // Add pending agents after sisyphus and hephaestus to maintain order
+   for (const [name, config] of pendingAgentConfigs) {
+     result[name] = config
+   }
+
    if (!disabledAgents.includes("atlas")) {
      const orchestratorOverride = agentOverrides["atlas"]
      const atlasRequirement = AGENT_MODEL_REQUIREMENTS["atlas"]