oh-my-opencode/src/plugin-handlers/AGENTS.md

# PLUGIN-HANDLERS KNOWLEDGE BASE

## OVERVIEW

Configuration orchestration layer. Runs once at plugin init — transforms raw OpenCode config into resolved agent/tool/permission structures.

## STRUCTURE
```
plugin-handlers/
├── config-handler.ts                  # Main orchestrator (45 lines) — 6-phase loading
├── agent-config-handler.ts            # Agent loading pipeline (197 lines)
├── plan-model-inheritance.ts          # Plan demotion logic (28 lines)
├── prometheus-agent-config-builder.ts # Prometheus config builder (99 lines)
├── plugin-components-loader.ts        # Claude Code plugin discovery (71 lines, 10s timeout)
├── provider-config-handler.ts         # Provider config + model context limits cache
├── tool-config-handler.ts             # Permission migration (101 lines)
├── mcp-config-handler.ts              # Builtin + CC + plugin MCP merge
├── command-config-handler.ts          # Command/skill parallel discovery
├── category-config-resolver.ts        # Category lookup
├── agent-priority-order.ts            # Agent ordering (sisyphus, hephaestus, prometheus, atlas first)
├── plan-model-inheritance.test.ts     # 3696 lines of tests
├── config-handler.test.ts             # 1061 lines of tests
└── index.ts                           # Barrel exports
```

## CONFIG LOADING FLOW (6 phases, sequential)

1. `applyProviderConfig` → Cache model context limits, detect anthropic-beta headers
2. `loadPluginComponents` → Discover Claude Code plugins (10s timeout, error isolation)
3. `applyAgentConfig` → Load all agents, sisyphus/prometheus/plan demotion
4. `applyToolConfig` → Agent-specific tool permissions (grep_app, task, teammate)
5. `applyMcpConfig` → Merge builtin + Claude Code + plugin MCPs
6. `applyCommandConfig` → Merge builtin + user + project + opencode commands/skills

## PLAN MODEL INHERITANCE

When `sisyphus_agent.planner_enabled === true`:
1. Prometheus config → extract model settings (model, variant, temperature, ...)
2. Apply user `agents.plan` overrides (plan override wins)
3. Set `mode: "subagent"` (plan becomes subagent, not primary)
4. Strip prompt/permission/description (only model settings inherited)

## AGENT LOADING ORDER

1. Builtin agents (sisyphus, hephaestus, oracle, ...)
2. Sisyphus-Junior (if sisyphus enabled)
3. OpenCode-Builder (if `default_builder_enabled`)
4. Prometheus (if `planner_enabled`)
5. User agents → Project agents → Plugin agents → Custom agents

**Reordered** by `reorderAgentsByPriority()`: sisyphus, hephaestus, prometheus, atlas first.

## TOOL PERMISSIONS

| Agent | Special Permissions |
|-------|---------------------|
| librarian | grep_app_* allowed |
| atlas | task, task_*, teammate allowed |
| sisyphus | task, task_*, teammate, question allowed |
| hephaestus | task, question allowed |
| multimodal-looker | Denies task, look_at |

## INTEGRATION

Created in `create-managers.ts`, exposed as `config` hook in `plugin-interface.ts`. OpenCode calls it during session init.