AGENTS.md

1# src/plugin-handlers/ -- 6-Phase Config Loading Pipeline
2 
3**Generated:** 2026-07-17 / 7d664b96b
4 
5## CRITICAL: AGENT ORDERING
6 
7The default agent order is **sisyphus → hephaestus → prometheus → atlas**. User config may override it with `agent_order`; omitted core agents fall back to this default order.
8 
9This order is enforced via two cooperating mechanisms:
101. `DEFAULT_AGENT_ORDER` in `src/shared/agent-ordering.ts` supplies the fallback order used when `agent_order` is absent or incomplete.
112. `reorderAgentsByPriority()` in `agent-priority-order.ts` controls object key insertion order in the agent map produced by `applyAgentConfig`.
123. `installAgentSortShim()` in `src/shared/agent-sort-shim.ts` narrows `Array.prototype.toSorted` and `Array.prototype.sort` so that whenever the sorted array contains two or more ranked agent objects, OpenCode's `Agent.list()` (and any other sort site) returns the active configured/default order. The shim is installed once at plugin entry, before any agent registration, and its rank map is updated after plugin config loads.
13 
14### Why a Sort Shim
15 
16OpenCode 1.4.x sorts agents purely by `agent.name` via Remeda `sortBy`, which uses native string `<` / `>` comparison (NOT `localeCompare`). It currently ignores the agent `order` field. Until that lands (sst/opencode#19127), object-key insertion order alone does not survive `Agent.list()`, and biasing the sort key with invisible characters all failed:
17- ZWSP (U+200B): `Bun.stringWidth` returns 0 but terminals (Ghostty, WezTerm, Alacritty, certain Windows Terminal builds) render it as 1-cell wide. Visible gap in the status bar; column truncation in the agent picker (#3259).
18- U+2060 WORD JOINER, U+00AD SOFT HYPHEN, ANSI escape: same width-mismatch class.
19- Removing the prefix and relying on insertion order alone falls back to alphabetical Atlas → Hephaestus → Prometheus → Sisyphus.
20 
21The sort shim resolves this by intercepting only the narrow case it cares about, with strict activation guards to prevent collateral damage from a global prototype patch:
22- The activation predicate (`isAgentArray`) requires `arr.length >= 2`, every element is a non-null object with a string `.name`, and at least 2 elements have a `.name` ranked by the active order. This rejects mixed-type arrays (numbers, strings, plain objects without `.name`) so unrelated `.sort()` / `.toSorted()` calls execute native semantics.
23- The comparator never throws on mixed input -- it defensively extracts `.name` and falls back to the user-supplied `compareFn`.
24- `installAgentSortShim()` is idempotent.
25 
26### History
27 
28Agent ordering has caused 15+ commits, 8+ PRs, and multiple reverts. Notable milestones:
29- #3260 (merged): removed ZWSP injection. Reverted by `0d5b08744` because OpenCode 1.4.x ignores `order`, and removal alone causes alphabetical fallback (Atlas → Hephaestus → Prometheus → Sisyphus).
30- #3329 (merged): introduced `CANONICAL_CORE_AGENT_ORDER` and locked the policy. Insertion order alone still does not survive OpenCode's `Agent.list()` sort.
31- #3267 (closed): proposed a sort shim. Closed at the time on the assumption that #3329 was sufficient. Revived in this commit with cubic P1 mitigations (defensive comparator, strict activation predicate, idempotent install).
32 
33### Forbidden Patterns
34 
35DO NOT introduce:
36- ZWSP, U+2060, U+00AD, ANSI escape, or any other invisible / control character in agent names, display names, or object keys.
37- ASCII spaces or other visible sort prefixes on agent names.
38- Alternative ordering constants outside `DEFAULT_AGENT_ORDER` / `CANONICAL_CORE_AGENT_ORDER`, or ordering code that bypasses `validateAgentOrder`.
39- Object.entries() iteration-order dependencies.
40- Agent name string comparisons that skip `getAgentConfigKey` / `stripInvisibleAgentCharacters` (legacy ZWSP-baked data must keep resolving).
41 
42The sort shim in `src/shared/agent-sort-shim.ts` is the ONLY supported runtime ordering mechanism. Remove it once OpenCode honors the agent `order` field (sst/opencode#19127).
43 
44PRs attempting any of the forbidden patterns will be rejected.
45 
46## OVERVIEW
47 
4814 non-test files implementing the `ConfigHandler` -- the `config` hook handler. Executes 6 sequential phases to register agents, tools, MCPs, and commands with OpenCode.
49 
50## 6-PHASE PIPELINE
51 
52| Phase | Handler | Purpose |
53|-------|---------|---------|
54| 1 | `applyProviderConfig` | Cache model context limits, detect anthropic-beta headers |
55| 2 | `loadPluginComponents` | Discover Claude Code plugins (10s timeout, error isolation) |
56| 3 | `applyAgentConfig` | Load agents from 5 sources, skill discovery, plan demotion |
57| 4 | `applyToolConfig` | Agent-specific tool permissions |
58| 5 | `applyMcpConfig` | Merge builtin + CC + plugin MCPs |
59| 6 | `applyCommandConfig` | Merge commands/skills from 9 parallel sources |
60 
61## FILES
62 
63| File | Lines | Purpose |
64|------|-------|---------|
65| `config-handler.ts` | ~200 | Main orchestrator, 6-phase sequential |
66| `plugin-components-loader.ts` | ~100 | CC plugin discovery (10s timeout) |
67| `agent-config-handler.ts` | ~300 | Agent loading + skill discovery from 5 sources |
68| `mcp-config-handler.ts` | ~150 | Builtin + CC + plugin MCP merge |
69| `command-config-handler.ts` | ~200 | 9 parallel sources for commands/skills |
70| `tool-config-handler.ts` | ~100 | Agent-specific tool grants/denials |
71| `provider-config-handler.ts` | ~80 | Provider config + model cache |
72| `prometheus-agent-config-builder.ts` | ~140 | Prometheus config with model + fallback_models resolution |
73| `plan-model-inheritance.ts` | 28 | Plan demotion logic (inherits model settings incl. fallback_models) |
74| `agent-priority-order.ts` | ~30 | sisyphus, hephaestus, prometheus, atlas first |
75| `agent-key-remapper.ts` | ~30 | Agent key → display name |
76| `category-config-resolver.ts` | ~40 | User vs default category lookup |
77| `index.ts` | ~10 | Barrel exports |
78 
79## TOOL PERMISSIONS
80 
81| Agent | Granted | Denied |
82|-------|---------|--------|
83| Librarian | grep_app_* | - |
84| Atlas, Sisyphus, Prometheus | task, task_*, teammate | - |
85| Hephaestus | task | - |
86| Default (all others) | - | grep_app_*, task_*, teammate, LSP |
87 
88## MULTI-LEVEL CONFIG MERGE
89 
90```
91User (~/.omo/omo.jsonc)
92  ↓ deepMerge
93Project (.omo/omo.jsonc)
94  ↓ Zod defaults
95Final Config
96```
97 
98- `agents`, `categories`, `claude_code`: deep merged
99- `disabled_*` arrays: Set union
100