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>
2026-02-01 19:26:57 +09:00
parent 5f053cd75b
commit 64825158a7
45 changed files with 2617 additions and 970 deletions
@@ -1,19 +1,27 @@
 # AGENTS KNOWLEDGE BASE

 ## OVERVIEW
-10 AI agents for multi-model orchestration. Sisyphus (primary), Atlas (orchestrator), oracle, librarian, explore, multimodal-looker, Prometheus, Metis, Momus, Sisyphus-Junior.
+
+11 AI agents for multi-model orchestration. Each agent has factory function + metadata + fallback chains.
+
+**Primary Agents** (respect UI model selection):
+- Sisyphus, Atlas, Prometheus
+
+**Subagents** (use own fallback chains):
+- Hephaestus, Oracle, Librarian, Explore, Multimodal-Looker, Metis, Momus, Sisyphus-Junior

 ## STRUCTURE
 ```
 agents/
 ├── atlas.ts                    # Master Orchestrator (holds todo list)
 ├── sisyphus.ts                 # Main prompt (SF Bay Area engineer identity)
+├── hephaestus.ts               # Autonomous Deep Worker (GPT 5.2 Codex, "The Legitimate Craftsman")
 ├── sisyphus-junior.ts          # Delegated task executor (category-spawned)
 ├── oracle.ts                   # Strategic advisor (GPT-5.2)
 ├── librarian.ts                # Multi-repo research (GitHub CLI, Context7)
-├── explore.ts                  # Fast contextual grep (Grok Code)
+├── explore.ts                  # Fast contextual grep (Claude Haiku)
 ├── multimodal-looker.ts        # Media analyzer (Gemini 3 Flash)
-├── prometheus-prompt.ts        # Planning (Interview/Consultant mode, 1196 lines)
+├── prometheus-prompt.ts        # Planning (Interview/Consultant mode, 1283 lines)
 ├── metis.ts                    # Pre-planning analysis (Gap detection)
 ├── momus.ts                    # Plan reviewer (Ruthless fault-finding)
 ├── dynamic-agent-prompt-builder.ts  # Dynamic prompt generation
@@ -26,6 +34,7 @@ agents/
 | Agent | Model | Temp | Purpose |
 |-------|-------|------|---------|
 | Sisyphus | anthropic/claude-opus-4-5 | 0.1 | Primary orchestrator (fallback: kimi-k2.5 → glm-4.7 → gpt-5.2-codex → gemini-3-pro) |
+| Hephaestus | openai/gpt-5.2-codex | 0.1 | Autonomous deep worker, "The Legitimate Craftsman" (requires gpt-5.2-codex, no fallback) |
 | Atlas | anthropic/claude-sonnet-4-5 | 0.1 | Master orchestrator (fallback: kimi-k2.5 → gpt-5.2) |
 | oracle | openai/gpt-5.2 | 0.1 | Consultation, debugging |
 | librarian | zai-coding-plan/glm-4.7 | 0.1 | Docs, GitHub search (fallback: glm-4.7-free) |
@@ -0,0 +1,509 @@
+import type { AgentConfig } from "@opencode-ai/sdk"
+import type { AgentMode } from "./types"
+import type { AvailableAgent, AvailableTool, AvailableSkill, AvailableCategory } from "./dynamic-agent-prompt-builder"
+import {
+  buildKeyTriggersSection,
+  buildToolSelectionTable,
+  buildExploreSection,
+  buildLibrarianSection,
+  buildCategorySkillsDelegationGuide,
+  buildDelegationTable,
+  buildOracleSection,
+  buildHardBlocksSection,
+  buildAntiPatternsSection,
+  categorizeTools,
+} from "./dynamic-agent-prompt-builder"
+
+const MODE: AgentMode = "primary"
+
+/**
+ * Hephaestus - The Autonomous Deep Worker
+ *
+ * Named after the Greek god of forge, fire, metalworking, and craftsmanship.
+ * Inspired by AmpCode's deep mode - autonomous problem-solving with thorough research.
+ *
+ * Powered by GPT 5.2 Codex with medium reasoning effort.
+ * Optimized for:
+ * - Goal-oriented autonomous execution (not step-by-step instructions)
+ * - Deep exploration before decisive action
+ * - Active use of explore/librarian agents for comprehensive context
+ * - End-to-end task completion without premature stopping
+ */
+
+function buildHephaestusPrompt(
+  availableAgents: AvailableAgent[] = [],
+  availableTools: AvailableTool[] = [],
+  availableSkills: AvailableSkill[] = [],
+  availableCategories: AvailableCategory[] = []
+): string {
+  const keyTriggers = buildKeyTriggersSection(availableAgents, availableSkills)
+  const toolSelection = buildToolSelectionTable(availableAgents, availableTools, availableSkills)
+  const exploreSection = buildExploreSection(availableAgents)
+  const librarianSection = buildLibrarianSection(availableAgents)
+  const categorySkillsGuide = buildCategorySkillsDelegationGuide(availableCategories, availableSkills)
+  const delegationTable = buildDelegationTable(availableAgents)
+  const oracleSection = buildOracleSection(availableAgents)
+  const hardBlocks = buildHardBlocksSection()
+  const antiPatterns = buildAntiPatternsSection()
+
+  return `You are Hephaestus, an autonomous deep worker for software engineering.
+
+## Reasoning Configuration (ROUTER NUDGE - GPT 5.2)
+
+Engage MEDIUM reasoning effort for all code modifications and architectural decisions.
+Prioritize logical consistency, codebase pattern matching, and thorough verification over response speed.
+For complex multi-file refactoring or debugging: escalate to HIGH reasoning effort.
+
+## Identity & Expertise
+
+You operate as a **Senior Staff Engineer** with deep expertise in:
+- Repository-scale architecture comprehension
+- Autonomous problem decomposition and execution
+- Multi-file refactoring with full context awareness
+- Pattern recognition across large codebases
+
+You do not guess. You verify. You do not stop early. You complete.
+
+## Hard Constraints (MUST READ FIRST - GPT 5.2 Constraint-First)
+
+${hardBlocks}
+
+${antiPatterns}
+
+## Success Criteria (COMPLETION DEFINITION)
+
+A task is COMPLETE when ALL of the following are TRUE:
+1. All requested functionality implemented exactly as specified
+2. \`lsp_diagnostics\` returns zero errors on ALL modified files
+3. Build command exits with code 0 (if applicable)
+4. Tests pass (or pre-existing failures documented)
+5. No temporary/debug code remains
+6. Code matches existing codebase patterns (verified via exploration)
+7. Evidence provided for each verification step
+
+**If ANY criterion is unmet, the task is NOT complete.**
+
+## Phase 0 - Intent Gate (EVERY task)
+
+${keyTriggers}
+
+### Step 1: Classify Task Type
+
+| Type | Signal | Action |
+|------|--------|--------|
+| **Trivial** | Single file, known location, <10 lines | Direct tools only (UNLESS Key Trigger applies) |
+| **Explicit** | Specific file/line, clear command | Execute directly |
+| **Exploratory** | "How does X work?", "Find Y" | Fire explore (1-3) + tools in parallel |
+| **Open-ended** | "Improve", "Refactor", "Add feature" | Full Execution Loop required |
+| **Ambiguous** | Unclear scope, multiple interpretations | Ask ONE clarifying question |
+
+### Step 2: Handle Ambiguity WITHOUT Questions (GPT 5.2 CRITICAL)
+
+**NEVER ask clarifying questions unless the user explicitly asks you to.**
+
+**Default: EXPLORE FIRST. Questions are the LAST resort.**
+
+| Situation | Action |
+|-----------|--------|
+| Single valid interpretation | Proceed immediately |
+| Missing info that MIGHT exist | **EXPLORE FIRST** - use tools (gh, git, grep, explore agents) to find it |
+| Multiple plausible interpretations | Cover ALL likely intents comprehensively, don't ask |
+| Info not findable after exploration | State your best-guess interpretation, proceed with it |
+| Truly impossible to proceed | Ask ONE precise question (LAST RESORT) |
+
+**EXPLORE-FIRST Protocol:**
+\`\`\`
+// WRONG: Ask immediately
+User: "Fix the PR review comments"
+Agent: "What's the PR number?"  // BAD - didn't even try to find it
+
+// CORRECT: Explore first
+User: "Fix the PR review comments"
+Agent: *runs gh pr list, gh pr view, searches recent commits*
+       *finds the PR, reads comments, proceeds to fix*
+       // Only asks if truly cannot find after exhaustive search
+\`\`\`
+
+**When ambiguous, cover multiple intents:**
+\`\`\`
+// If query has 2-3 plausible meanings:
+// DON'T ask "Did you mean A or B?"
+// DO provide comprehensive coverage of most likely intent
+// DO note: "I interpreted this as X. If you meant Y, let me know."
+\`\`\`
+
+### Step 3: Validate Before Acting
+
+**Delegation Check (MANDATORY before acting directly):**
+1. Is there a specialized agent that perfectly matches this request?
+2. If not, is there a \`delegate_task\` category that best describes this task? What skills are available to equip the agent with?
+   - MUST FIND skills to use: \`delegate_task(load_skills=[{skill1}, ...])\`
+3. Can I do it myself for the best result, FOR SURE?
+
+**Default Bias: DELEGATE for complex tasks. Work yourself ONLY when trivial.**
+
+### Judicious Initiative (CRITICAL)
+
+**Use good judgment. EXPLORE before asking. Deliver results, not questions.**
+
+**Core Principles:**
+- Make reasonable decisions without asking
+- When info is missing: SEARCH FOR IT using tools before asking
+- Trust your technical judgment for implementation details
+- Note assumptions in final message, not as questions mid-work
+
+**Exploration Hierarchy (MANDATORY before any question):**
+1. **Direct tools**: \`gh pr list\`, \`git log\`, \`grep\`, \`rg\`, file reads
+2. **Explore agents**: Fire 2-3 parallel background searches
+3. **Librarian agents**: Check docs, GitHub, external sources
+4. **Context inference**: Use surrounding context to make educated guess
+5. **LAST RESORT**: Ask ONE precise question (only if 1-4 all failed)
+
+**If you notice a potential issue:**
+\`\`\`
+// DON'T DO THIS:
+"I notice X might cause Y. Should I proceed?"
+
+// DO THIS INSTEAD:
+*Proceed with implementation*
+*In final message:* "Note: I noticed X. I handled it by doing Z to avoid Y."
+\`\`\`
+
+**Only stop for TRUE blockers** (mutually exclusive requirements, impossible constraints).
+
+---
+
+## Exploration & Research
+
+${toolSelection}
+
+${exploreSection}
+
+${librarianSection}
+
+### Parallel Execution (DEFAULT behavior - NON-NEGOTIABLE)
+
+**Explore/Librarian = Grep, not consultants. ALWAYS run them in parallel as background tasks.**
+
+\`\`\`typescript
+// CORRECT: Always background, always parallel
+// Prompt structure: [CONTEXT: what I'm doing] + [GOAL: what I'm trying to achieve] + [QUESTION: what I need to know] + [REQUEST: what to find]
+// Contextual Grep (internal)
+delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="I'm implementing user authentication for our API. I need to understand how auth is currently structured in this codebase. Find existing auth implementations, patterns, and where credentials are validated.")
+delegate_task(subagent_type="explore", run_in_background=true, load_skills=[], prompt="I'm adding error handling to the auth flow. I want to follow existing project conventions for consistency. Find how errors are handled elsewhere - patterns, custom error classes, and response formats used.")
+// Reference Grep (external)
+delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="I'm implementing JWT-based auth and need to ensure security best practices. Find official JWT documentation and security recommendations - token expiration, refresh strategies, and common vulnerabilities to avoid.")
+delegate_task(subagent_type="librarian", run_in_background=true, load_skills=[], prompt="I'm building Express middleware for auth and want production-quality patterns. Find how established Express apps handle authentication - middleware structure, session management, and error handling examples.")
+// Continue immediately - collect results when needed
+
+// WRONG: Sequential or blocking - NEVER DO THIS
+result = delegate_task(..., run_in_background=false)  // Never wait synchronously for explore/librarian
+\`\`\`
+
+**Rules:**
+- Fire 2-5 explore agents in parallel for any non-trivial codebase question
+- NEVER use \`run_in_background=false\` for explore/librarian
+- Continue your work immediately after launching
+- Collect results with \`background_output(task_id="...")\` when needed
+- BEFORE final answer: \`background_cancel(all=true)\` to clean up
+
+### Search Stop Conditions
+
+STOP searching when:
+- You have enough context to proceed confidently
+- Same information appearing across multiple sources
+- 2 search iterations yielded no new useful data
+- Direct answer found
+
+**DO NOT over-explore. Time is precious.**
+
+---
+
+## Execution Loop (EXPLORE → PLAN → DECIDE → EXECUTE)
+
+For any non-trivial task, follow this loop:
+
+### Step 1: EXPLORE (Parallel Background Agents)
+
+Fire 2-5 explore/librarian agents IN PARALLEL to gather comprehensive context.
+
+### Step 2: PLAN (Create Work Plan)
+
+After collecting exploration results, create a concrete work plan:
+- List all files to be modified
+- Define the specific changes for each file
+- Identify dependencies between changes
+- Estimate complexity (trivial / moderate / complex)
+
+### Step 3: DECIDE (Self vs Delegate)
+
+For EACH task in your plan, explicitly decide:
+
+| Complexity | Criteria | Decision |
+|------------|----------|----------|
+| **Trivial** | <10 lines, single file, obvious change | Do it yourself |
+| **Moderate** | Single domain, clear pattern, <100 lines | Do it yourself OR delegate |
+| **Complex** | Multi-file, unfamiliar domain, >100 lines | MUST delegate |
+
+**When in doubt: DELEGATE. The overhead is worth the quality.**
+
+### Step 4: EXECUTE
+
+Execute your plan:
+- If doing yourself: make surgical, minimal changes
+- If delegating: provide exhaustive context and success criteria in the prompt
+
+### Step 5: VERIFY
+
+After execution:
+1. Run \`lsp_diagnostics\` on ALL modified files
+2. Run build command (if applicable)
+3. Run tests (if applicable)
+4. Confirm all Success Criteria are met
+
+**If verification fails: return to Step 1 (max 3 iterations, then consult Oracle)**
+
+---
+
+## Implementation
+
+${categorySkillsGuide}
+
+${delegationTable}
+
+### Delegation Prompt Structure (MANDATORY - ALL 6 sections):
+
+When delegating, your prompt MUST include:
+
+\`\`\`
+1. TASK: Atomic, specific goal (one action per delegation)
+2. EXPECTED OUTCOME: Concrete deliverables with success criteria
+3. REQUIRED TOOLS: Explicit tool whitelist (prevents tool sprawl)
+4. MUST DO: Exhaustive requirements - leave NOTHING implicit
+5. MUST NOT DO: Forbidden actions - anticipate and block rogue behavior
+6. CONTEXT: File paths, existing patterns, constraints
+\`\`\`
+
+**Vague prompts = rejected. Be exhaustive.**
+
+### Delegation Verification (MANDATORY)
+
+AFTER THE WORK YOU DELEGATED SEEMS DONE, ALWAYS VERIFY THE RESULTS AS FOLLOWING:
+- DOES IT WORK AS EXPECTED?
+- DOES IT FOLLOW THE EXISTING CODEBASE PATTERN?
+- DID THE EXPECTED RESULT COME OUT?
+- DID THE AGENT FOLLOW "MUST DO" AND "MUST NOT DO" REQUIREMENTS?
+
+**NEVER trust subagent self-reports. ALWAYS verify with your own tools.**
+
+### Session Continuity (MANDATORY)
+
+Every \`delegate_task()\` output includes a session_id. **USE IT.**
+
+**ALWAYS continue when:**
+| Scenario | Action |
+|----------|--------|
+| Task failed/incomplete | \`session_id="{session_id}", prompt="Fix: {specific error}"\` |
+| Follow-up question on result | \`session_id="{session_id}", prompt="Also: {question}"\` |
+| Multi-turn with same agent | \`session_id="{session_id}"\` - NEVER start fresh |
+| Verification failed | \`session_id="{session_id}", prompt="Failed verification: {error}. Fix."\` |
+
+**After EVERY delegation, STORE the session_id for potential continuation.**
+
+${oracleSection ? `
+${oracleSection}
+` : ""}
+
+## Role & Agency (CRITICAL - READ CAREFULLY)
+
+**KEEP GOING UNTIL THE QUERY IS COMPLETELY RESOLVED.**
+
+Only terminate your turn when you are SURE the problem is SOLVED.
+Autonomously resolve the query to the BEST of your ability.
+Do NOT guess. Do NOT ask unnecessary questions. Do NOT stop early.
+
+**Completion Checklist (ALL must be true):**
+1. User asked for X → X is FULLY implemented (not partial, not "basic version")
+2. X passes lsp_diagnostics (zero errors on ALL modified files)
+3. X passes related tests (or you documented pre-existing failures)
+4. Build succeeds (if applicable)
+5. You have EVIDENCE for each verification step
+
+**FORBIDDEN (will result in incomplete work):**
+- "I've made the changes, let me know if you want me to continue" → NO. FINISH IT.
+- "Should I proceed with X?" → NO. JUST DO IT.
+- "Do you want me to run tests?" → NO. RUN THEM YOURSELF.
+- "I noticed Y, should I fix it?" → NO. FIX IT OR NOTE IT IN FINAL MESSAGE.
+- Stopping after partial implementation → NO. 100% OR NOTHING.
+- Asking about implementation details → NO. YOU DECIDE.
+
+**CORRECT behavior:**
+- Keep going until COMPLETELY done. No intermediate checkpoints with user.
+- Run verification (lint, tests, build) WITHOUT asking—just do it.
+- Make decisions. Course-correct only on CONCRETE failure.
+- Note assumptions in final message, not as questions mid-work.
+- If blocked, consult Oracle or explore more—don't ask user for implementation guidance.
+
+**The only valid reasons to stop and ask (AFTER exhaustive exploration):**
+- Mutually exclusive requirements (cannot satisfy both A and B)
+- Truly missing info that CANNOT be found via tools/exploration/inference
+- User explicitly requested clarification
+
+**Before asking ANY question, you MUST have:**
+1. Tried direct tools (gh, git, grep, file reads)
+2. Fired explore/librarian agents
+3. Attempted context inference
+4. Exhausted all findable information
+
+**You are autonomous. EXPLORE first. Ask ONLY as last resort.**
+
+## Output Contract (UNIFIED)
+
+<output_contract>
+**Format:**
+- Default: 3-6 sentences or ≤5 bullets
+- Simple yes/no questions: ≤2 sentences
+- Complex multi-file tasks: 1 overview paragraph + ≤5 tagged bullets (What, Where, Risks, Next, Open)
+
+**Style:**
+- Start work immediately. No acknowledgments ("I'm on it", "Let me...")
+- Answer directly without preamble
+- Don't summarize unless asked
+- One-word answers acceptable when appropriate
+
+**Updates:**
+- Brief updates (1-2 sentences) only when starting major phase or plan changes
+- Avoid narrating routine tool calls
+- Each update must include concrete outcome ("Found X", "Updated Y")
+
+**Scope:**
+- Implement EXACTLY what user requests
+- No extra features, no embellishments
+- Simplest valid interpretation for ambiguous instructions
+</output_contract>
+
+## Response Compaction (LONG CONTEXT HANDLING)
+
+When working on long sessions or complex multi-file tasks:
+- Periodically summarize your working state internally
+- Track: files modified, changes made, verifications completed, next steps
+- Do not lose track of the original request across many tool calls
+- If context feels overwhelming, pause and create a checkpoint summary
+
+## Code Quality Standards
+
+### Codebase Style Check (MANDATORY)
+
+**BEFORE writing ANY code:**
+1. SEARCH the existing codebase to find similar patterns/styles
+2. Your code MUST match the project's existing conventions
+3. Write READABLE code - no clever tricks
+4. If unsure about style, explore more files until you find the pattern
+
+**When implementing:**
+- Match existing naming conventions
+- Match existing indentation and formatting
+- Match existing import styles
+- Match existing error handling patterns
+- Match existing comment styles (or lack thereof)
+
+### Minimal Changes
+
+- Default to ASCII
+- Add comments only for non-obvious blocks
+- Make the **minimum change** required
+
+### Edit Protocol
+
+1. Always read the file first
+2. Include sufficient context for unique matching
+3. Use \`apply_patch\` for edits
+4. Use multiple context blocks when needed
+
+## Verification & Completion
+
+### Post-Change Verification (MANDATORY - DO NOT SKIP)
+
+**After EVERY implementation, you MUST:**
+
+1. **Run \`lsp_diagnostics\` on ALL modified files**
+   - Zero errors required before proceeding
+   - Fix any errors YOU introduced (not pre-existing ones)
+
+2. **Find and run related tests**
+   - Search for test files: \`*.test.ts\`, \`*.spec.ts\`, \`__tests__/*\`
+   - Look for tests in same directory or \`tests/\` folder
+   - Pattern: if you modified \`foo.ts\`, look for \`foo.test.ts\`
+   - Run: \`bun test <test-file>\` or project's test command
+   - If no tests exist for the file, note it explicitly
+
+3. **Run typecheck if TypeScript project**
+   - \`bun run typecheck\` or \`tsc --noEmit\`
+
+4. **If project has build command, run it**
+   - Ensure exit code 0
+
+**DO NOT report completion until all verification steps pass.**
+
+### Evidence Requirements
+
+| Action | Required Evidence |
+|--------|-------------------|
+| File edit | \`lsp_diagnostics\` clean |
+| Build command | Exit code 0 |
+| Test run | Pass (or pre-existing failures noted) |
+
+**NO EVIDENCE = NOT COMPLETE.**
+
+## Failure Recovery
+
+### Fix Protocol
+
+1. Fix root causes, not symptoms
+2. Re-verify after EVERY fix attempt
+3. Never shotgun debug
+
+### After 3 Consecutive Failures
+
+1. **STOP** all edits
+2. **REVERT** to last working state
+3. **DOCUMENT** what failed
+4. **CONSULT** Oracle with full context
+5. If unresolved, **ASK USER**
+
+**Never**: Leave code broken, delete failing tests, continue hoping
+
+## Soft Guidelines
+
+- Prefer existing libraries over new dependencies
+- Prefer small, focused changes over large refactors
+- When uncertain about scope, ask`
+}
+
+export function createHephaestusAgent(
+  model: string,
+  availableAgents?: AvailableAgent[],
+  availableToolNames?: string[],
+  availableSkills?: AvailableSkill[],
+  availableCategories?: AvailableCategory[]
+): AgentConfig {
+  const tools = availableToolNames ? categorizeTools(availableToolNames) : []
+  const skills = availableSkills ?? []
+  const categories = availableCategories ?? []
+  const prompt = availableAgents
+    ? buildHephaestusPrompt(availableAgents, tools, skills, categories)
+    : buildHephaestusPrompt([], tools, skills, categories)
+
+  return {
+    description:
+      "Autonomous Deep Worker - goal-oriented execution with GPT 5.2 Codex. Explores thoroughly before acting, uses explore/librarian agents for comprehensive context, completes tasks end-to-end. Inspired by AmpCode deep mode. (Hephaestus - OhMyOpenCode)",
+    mode: MODE,
+    model,
+    maxTokens: 32000,
+    prompt,
+    color: "#FF4500", // Magma Orange - forge heat, distinct from Prometheus purple
+    permission: { question: "allow", call_omo_agent: "deny" } as AgentConfig["permission"],
+    reasoningEffort: "medium",
+  }
+}
+createHephaestusAgent.mode = MODE
@@ -72,6 +72,7 @@ export function isGptModel(model: string): boolean {

 export type BuiltinAgentName =
  | "sisyphus"
+  | "hephaestus"
  | "oracle"
  | "librarian"
  | "explore"
@@ -1,61 +1,78 @@
-import { describe, test, expect, beforeEach, spyOn, afterEach } from "bun:test"
+import { describe, test, expect, beforeEach, afterEach, spyOn } from "bun:test"
 import { createBuiltinAgents } from "./utils"
 import type { AgentConfig } from "@opencode-ai/sdk"
 import { clearSkillCache } from "../features/opencode-skill-loader/skill-content"
 import * as connectedProvidersCache from "../shared/connected-providers-cache"
 import * as modelAvailability from "../shared/model-availability"
+import * as shared from "../shared"

 const TEST_DEFAULT_MODEL = "anthropic/claude-opus-4-5"

 describe("createBuiltinAgents with model overrides", () => {
-  test("Sisyphus with default model has thinking config", async () => {
-    // given - no overrides, using systemDefaultModel
+  test("Sisyphus with default model has thinking config when all models available", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set([
+        "anthropic/claude-opus-4-5",
+        "kimi-for-coding/k2p5",
+        "opencode/kimi-k2.5-free",
+        "zai-coding-plan/glm-4.7",
+        "opencode/glm-4.7-free",
+      ])
+    )

-    // when
-    const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL)
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})

-    // then
-    expect(agents.sisyphus.model).toBe("anthropic/claude-opus-4-5")
-    expect(agents.sisyphus.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
-    expect(agents.sisyphus.reasoningEffort).toBeUndefined()
+      // #then
+      expect(agents.sisyphus.model).toBe("anthropic/claude-opus-4-5")
+      expect(agents.sisyphus.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
+      expect(agents.sisyphus.reasoningEffort).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
  })

  test("Sisyphus with GPT model override has reasoningEffort, no thinking", async () => {
-    // given
+    // #given
    const overrides = {
      sisyphus: { model: "github-copilot/gpt-5.2" },
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then
+    // #then
    expect(agents.sisyphus.model).toBe("github-copilot/gpt-5.2")
    expect(agents.sisyphus.reasoningEffort).toBe("medium")
    expect(agents.sisyphus.thinking).toBeUndefined()
  })

-  test("Sisyphus uses system default when no availableModels provided", async () => {
-    // given
+  test("Sisyphus is not created when no availableModels provided (requiresAnyModel)", async () => {
+    // #given
    const systemDefaultModel = "anthropic/claude-opus-4-5"
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(new Set())

-    // when
-    const agents = await createBuiltinAgents([], {}, undefined, systemDefaultModel)
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, systemDefaultModel, undefined, undefined, [], {})

-    // then - falls back to system default when no availability match
-    expect(agents.sisyphus.model).toBe("anthropic/claude-opus-4-5")
-    expect(agents.sisyphus.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
-    expect(agents.sisyphus.reasoningEffort).toBeUndefined()
+      // #then
+      expect(agents.sisyphus).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
  })

   test("Oracle uses connected provider fallback when availableModels is empty and cache exists", async () => {
-     // given - connected providers cache has "openai", which matches oracle's first fallback entry
+     // #given - connected providers cache has "openai", which matches oracle's first fallback entry
     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(["openai"])

-     // when
+     // #when
     const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL)

-     // then - oracle resolves via connected cache fallback to openai/gpt-5.2 (not system default)
+     // #then - oracle resolves via connected cache fallback to openai/gpt-5.2 (not system default)
     expect(agents.oracle.model).toBe("openai/gpt-5.2")
     expect(agents.oracle.reasoningEffort).toBe("medium")
     expect(agents.oracle.thinking).toBeUndefined()
@@ -63,28 +80,28 @@ describe("createBuiltinAgents with model overrides", () => {
   })

   test("Oracle created without model field when no cache exists (first run scenario)", async () => {
-     // given - no cache at all (first run)
+     // #given - no cache at all (first run)
     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(null)

-     // when
+     // #when
     const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL)

-     // then - oracle should be created with system default model (fallback to systemDefaultModel)
+     // #then - oracle should be created with system default model (fallback to systemDefaultModel)
     expect(agents.oracle).toBeDefined()
     expect(agents.oracle.model).toBe(TEST_DEFAULT_MODEL)
     cacheSpy.mockRestore?.()
   })

  test("Oracle with GPT model override has reasoningEffort, no thinking", async () => {
-    // given
+    // #given
    const overrides = {
      oracle: { model: "openai/gpt-5.2" },
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then
+    // #then
    expect(agents.oracle.model).toBe("openai/gpt-5.2")
    expect(agents.oracle.reasoningEffort).toBe("medium")
    expect(agents.oracle.textVerbosity).toBe("high")
@@ -92,15 +109,15 @@ describe("createBuiltinAgents with model overrides", () => {
  })

  test("Oracle with Claude model override has thinking, no reasoningEffort", async () => {
-    // given
+    // #given
    const overrides = {
      oracle: { model: "anthropic/claude-sonnet-4" },
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then
+    // #then
    expect(agents.oracle.model).toBe("anthropic/claude-sonnet-4")
    expect(agents.oracle.thinking).toEqual({ type: "enabled", budgetTokens: 32000 })
    expect(agents.oracle.reasoningEffort).toBeUndefined()
@@ -108,15 +125,15 @@ describe("createBuiltinAgents with model overrides", () => {
  })

   test("non-model overrides are still applied after factory rebuild", async () => {
-     // given
+     // #given
     const overrides = {
       sisyphus: { model: "github-copilot/gpt-5.2", temperature: 0.5 },
     }

-     // when
+     // #when
     const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-     // then
+     // #then
     expect(agents.sisyphus.model).toBe("github-copilot/gpt-5.2")
     expect(agents.sisyphus.temperature).toBe(0.5)
   })
@@ -124,42 +141,197 @@ describe("createBuiltinAgents with model overrides", () => {

 describe("createBuiltinAgents without systemDefaultModel", () => {
   test("agents created via connected cache fallback even without systemDefaultModel", async () => {
-     // given - connected cache has "openai", which matches oracle's fallback chain
+     // #given - connected cache has "openai", which matches oracle's fallback chain
     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(["openai"])

-     // when
+     // #when
     const agents = await createBuiltinAgents([], {}, undefined, undefined)

-     // then - connected cache enables model resolution despite no systemDefaultModel
+     // #then - connected cache enables model resolution despite no systemDefaultModel
     expect(agents.oracle).toBeDefined()
     expect(agents.oracle.model).toBe("openai/gpt-5.2")
     cacheSpy.mockRestore?.()
   })

   test("agents NOT created when no cache and no systemDefaultModel (first run without defaults)", async () => {
-     // given
+     // #given
     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(null)

-     // when
+     // #when
     const agents = await createBuiltinAgents([], {}, undefined, undefined)

-     // then
+     // #then
     expect(agents.oracle).toBeUndefined()
     cacheSpy.mockRestore?.()
   })

-   test("sisyphus created via connected cache fallback even without systemDefaultModel", async () => {
-     // given - connected cache has "anthropic", which matches sisyphus's first fallback entry
-     const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue(["anthropic"])
+  test("sisyphus created via connected cache fallback when all providers available", async () => {
+    // #given
+    const cacheSpy = spyOn(connectedProvidersCache, "readConnectedProvidersCache").mockReturnValue([
+      "anthropic", "kimi-for-coding", "opencode", "zai-coding-plan"
+    ])
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set([
+        "anthropic/claude-opus-4-5",
+        "kimi-for-coding/k2p5",
+        "opencode/kimi-k2.5-free",
+        "zai-coding-plan/glm-4.7",
+        "opencode/glm-4.7-free",
+      ])
+    )

-     // when
-     const agents = await createBuiltinAgents([], {}, undefined, undefined)
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, undefined, undefined, undefined, [], {})

-     // then - connected cache enables model resolution despite no systemDefaultModel
-     expect(agents.sisyphus).toBeDefined()
-     expect(agents.sisyphus.model).toBe("anthropic/claude-opus-4-5")
-     cacheSpy.mockRestore?.()
-   })
+      // #then
+      expect(agents.sisyphus).toBeDefined()
+      expect(agents.sisyphus.model).toBe("anthropic/claude-opus-4-5")
+    } finally {
+      cacheSpy.mockRestore()
+      fetchSpy.mockRestore()
+    }
+  })
+})
+
+describe("createBuiltinAgents with requiresModel gating", () => {
+  test("hephaestus is not created when gpt-5.2-codex is unavailable", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["anthropic/claude-opus-4-5"])
+    )
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.hephaestus).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("hephaestus is created when gpt-5.2-codex is available", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["openai/gpt-5.2-codex"])
+    )
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.hephaestus).toBeDefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("hephaestus is not created when availableModels is empty", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(new Set())
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.hephaestus).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("hephaestus is created when explicit config provided even if model unavailable", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["anthropic/claude-opus-4-5"])
+    )
+    const overrides = {
+      hephaestus: { model: "anthropic/claude-opus-4-5" },
+    }
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.hephaestus).toBeDefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+})
+
+describe("createBuiltinAgents with requiresAnyModel gating (sisyphus)", () => {
+  test("sisyphus is created when at least one fallback model is available", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["anthropic/claude-opus-4-5"])
+    )
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.sisyphus).toBeDefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("sisyphus is not created when availableModels is empty", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(new Set())
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.sisyphus).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("sisyphus is created when explicit config provided even if no models available", async () => {
+    // #given
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(new Set())
+    const overrides = {
+      sisyphus: { model: "anthropic/claude-opus-4-5" },
+    }
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.sisyphus).toBeDefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
+
+  test("sisyphus is not created when no fallback model is available (unrelated model only)", async () => {
+    // #given - only openai/gpt-5.2 available, not in sisyphus fallback chain
+    const fetchSpy = spyOn(shared, "fetchAvailableModels").mockResolvedValue(
+      new Set(["openai/gpt-5.2"])
+    )
+
+    try {
+      // #when
+      const agents = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL, undefined, undefined, [], {})
+
+      // #then
+      expect(agents.sisyphus).toBeUndefined()
+    } finally {
+      fetchSpy.mockRestore()
+    }
+  })
 })

 describe("buildAgent with category and skills", () => {
@@ -170,8 +342,12 @@ describe("buildAgent with category and skills", () => {
    clearSkillCache()
  })

+  afterEach(() => {
+    clearSkillCache()
+  })
+
  test("agent with category inherits category settings", () => {
-    // given - agent factory that sets category but no model
+    // #given - agent factory that sets category but no model
    const source = {
      "test-agent": () =>
        ({
@@ -180,15 +356,15 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then - category's built-in model is applied
+    // #then - category's built-in model is applied
    expect(agent.model).toBe("google/gemini-3-pro")
  })

  test("agent with category and existing model keeps existing model", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -198,15 +374,15 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then - explicit model takes precedence over category
+    // #then - explicit model takes precedence over category
    expect(agent.model).toBe("custom/model")
  })

  test("agent with category inherits variant", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -222,16 +398,16 @@ describe("buildAgent with category and skills", () => {
      },
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL, categories)

-    // then
+    // #then
    expect(agent.model).toBe("openai/gpt-5.2")
    expect(agent.variant).toBe("xhigh")
  })

  test("agent with skills has content prepended to prompt", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -241,17 +417,17 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    expect(agent.prompt).toContain("Role: Designer-Turned-Developer")
    expect(agent.prompt).toContain("Original prompt content")
    expect(agent.prompt).toMatch(/Designer-Turned-Developer[\s\S]*Original prompt content/s)
  })

  test("agent with multiple skills has all content prepended", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -261,16 +437,16 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    expect(agent.prompt).toContain("Role: Designer-Turned-Developer")
    expect(agent.prompt).toContain("Agent prompt")
  })

  test("agent without category or skills works as before", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -281,17 +457,17 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    expect(agent.model).toBe("custom/model")
    expect(agent.temperature).toBe(0.5)
    expect(agent.prompt).toBe("Base prompt")
  })

  test("agent with category and skills applies both", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -302,10 +478,10 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then - category's built-in model and skills are applied
+    // #then - category's built-in model and skills are applied
    expect(agent.model).toBe("openai/gpt-5.2-codex")
    expect(agent.variant).toBe("xhigh")
    expect(agent.prompt).toContain("Role: Designer-Turned-Developer")
@@ -313,7 +489,7 @@ describe("buildAgent with category and skills", () => {
  })

  test("agent with non-existent category has no effect", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -323,10 +499,10 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    // Note: The factory receives model, but if category doesn't exist, it's not applied
    // The agent's model comes from the factory output (which doesn't set model)
    expect(agent.model).toBeUndefined()
@@ -334,7 +510,7 @@ describe("buildAgent with category and skills", () => {
  })

  test("agent with non-existent skills only prepends found ones", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -344,16 +520,16 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    expect(agent.prompt).toContain("Role: Designer-Turned-Developer")
    expect(agent.prompt).toContain("Base prompt")
  })

  test("agent with empty skills array keeps original prompt", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -363,15 +539,15 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when
+    // #when
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then
+    // #then
    expect(agent.prompt).toBe("Base prompt")
  })

  test("agent with agent-browser skill resolves when browserProvider is set", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -381,16 +557,16 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when - browserProvider is "agent-browser"
+    // #when - browserProvider is "agent-browser"
    const agent = buildAgent(source["test-agent"], TEST_MODEL, undefined, undefined, "agent-browser")

-    // then - agent-browser skill content should be in prompt
+    // #then - agent-browser skill content should be in prompt
    expect(agent.prompt).toContain("agent-browser")
    expect(agent.prompt).toContain("Base prompt")
  })

  test("agent with agent-browser skill NOT resolved when browserProvider not set", () => {
-    // given
+    // #given
    const source = {
      "test-agent": () =>
        ({
@@ -400,10 +576,10 @@ describe("buildAgent with category and skills", () => {
        }) as AgentConfig,
    }

-    // when - no browserProvider (defaults to playwright)
+    // #when - no browserProvider (defaults to playwright)
    const agent = buildAgent(source["test-agent"], TEST_MODEL)

-    // then - agent-browser skill not found, only base prompt remains
+    // #then - agent-browser skill not found, only base prompt remains
    expect(agent.prompt).toBe("Base prompt")
    expect(agent.prompt).not.toContain("agent-browser open")
  })
@@ -411,36 +587,36 @@ describe("buildAgent with category and skills", () => {

 describe("override.category expansion in createBuiltinAgents", () => {
  test("standard agent override with category expands category properties", async () => {
-    // given
+    // #given
    const overrides = {
      oracle: { category: "ultrabrain" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
+    // #then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
    expect(agents.oracle).toBeDefined()
    expect(agents.oracle.model).toBe("openai/gpt-5.2-codex")
    expect(agents.oracle.variant).toBe("xhigh")
  })

  test("standard agent override with category AND direct variant - direct wins", async () => {
-    // given - ultrabrain has variant=xhigh, but direct override says "max"
+    // #given - ultrabrain has variant=xhigh, but direct override says "max"
    const overrides = {
      oracle: { category: "ultrabrain", variant: "max" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then - direct variant overrides category variant
+    // #then - direct variant overrides category variant
    expect(agents.oracle).toBeDefined()
    expect(agents.oracle.variant).toBe("max")
  })

  test("standard agent override with category AND direct reasoningEffort - direct wins", async () => {
-    // given - custom category has reasoningEffort=xhigh, direct override says "low"
+    // #given - custom category has reasoningEffort=xhigh, direct override says "low"
    const categories = {
      "test-cat": {
        model: "openai/gpt-5.2",
@@ -451,16 +627,16 @@ describe("override.category expansion in createBuiltinAgents", () => {
      oracle: { category: "test-cat", reasoningEffort: "low" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL, categories)

-    // then - direct reasoningEffort wins over category
+    // #then - direct reasoningEffort wins over category
    expect(agents.oracle).toBeDefined()
    expect(agents.oracle.reasoningEffort).toBe("low")
  })

  test("standard agent override with category applies reasoningEffort from category when no direct override", async () => {
-    // given - custom category has reasoningEffort, no direct reasoningEffort in override
+    // #given - custom category has reasoningEffort, no direct reasoningEffort in override
    const categories = {
      "reasoning-cat": {
        model: "openai/gpt-5.2",
@@ -471,54 +647,54 @@ describe("override.category expansion in createBuiltinAgents", () => {
      oracle: { category: "reasoning-cat" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL, categories)

-    // then - category reasoningEffort is applied
+    // #then - category reasoningEffort is applied
    expect(agents.oracle).toBeDefined()
    expect(agents.oracle.reasoningEffort).toBe("high")
  })

  test("sisyphus override with category expands category properties", async () => {
-    // given
+    // #given
    const overrides = {
      sisyphus: { category: "ultrabrain" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
+    // #then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
    expect(agents.sisyphus).toBeDefined()
    expect(agents.sisyphus.model).toBe("openai/gpt-5.2-codex")
    expect(agents.sisyphus.variant).toBe("xhigh")
  })

  test("atlas override with category expands category properties", async () => {
-    // given
+    // #given
    const overrides = {
      atlas: { category: "ultrabrain" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
+    // #then - ultrabrain category: model=openai/gpt-5.2-codex, variant=xhigh
    expect(agents.atlas).toBeDefined()
    expect(agents.atlas.model).toBe("openai/gpt-5.2-codex")
    expect(agents.atlas.variant).toBe("xhigh")
  })

  test("override with non-existent category has no effect on config", async () => {
-    // given
+    // #given
    const overrides = {
      oracle: { category: "non-existent-category" } as any,
    }

-    // when
+    // #when
    const agents = await createBuiltinAgents([], overrides, undefined, TEST_DEFAULT_MODEL)

-    // then - no category-specific variant/reasoningEffort applied from non-existent category
+    // #then - no category-specific variant/reasoningEffort applied from non-existent category
    expect(agents.oracle).toBeDefined()
    const agentsWithoutOverride = await createBuiltinAgents([], {}, undefined, TEST_DEFAULT_MODEL)
    expect(agents.oracle.model).toBe(agentsWithoutOverride.oracle.model)
@@ -527,7 +703,7 @@ describe("override.category expansion in createBuiltinAgents", () => {

 describe("Deadlock prevention - fetchAvailableModels must not receive client", () => {
   test("createBuiltinAgents should call fetchAvailableModels with undefined client to prevent deadlock", async () => {
-     // given - This test ensures we don't regress on issue #1301
+     // #given - This test ensures we don't regress on issue #1301
     // Passing client to fetchAvailableModels during createBuiltinAgents (called from config handler)
     // causes deadlock:
     // - Plugin init waits for server response (client.provider.list())
@@ -540,7 +716,7 @@ describe("Deadlock prevention - fetchAvailableModels must not receive client", (
       model: { list: () => Promise.resolve({ data: [] }) },
     }

-     // when - Even when client is provided, fetchAvailableModels must be called with undefined
+     // #when - Even when client is provided, fetchAvailableModels must be called with undefined
     await createBuiltinAgents(
       [],
       {},
@@ -552,7 +728,7 @@ describe("Deadlock prevention - fetchAvailableModels must not receive client", (
       mockClient // client is passed but should NOT be forwarded to fetchAvailableModels
     )

-     // then - fetchAvailableModels must be called with undefined as first argument (no client)
+     // #then - fetchAvailableModels must be called with undefined as first argument (no client)
     // This prevents the deadlock described in issue #1301
     expect(fetchSpy).toHaveBeenCalled()
     const firstCallArgs = fetchSpy.mock.calls[0]
@@ -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"]