AGENTS.md

1# src/tools/call-omo-agent/ — Direct Agent Invocation Tool
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
723 files. The `call_omo_agent` tool — direct invocation of named agents (explore, librarian only). Distinct from `delegate-task`: no category system, no skill loading, no model selection. Fixed agent set, same execution modes (background/sync).
8 
9## DISTINCTION FROM delegate-task
10 
11| Aspect | `call_omo_agent` | `delegate-task` (`task`) |
12|--------|-----------------|--------------------------|
13| Agent selection | Named agent (explore/librarian) | Category or subagent_type |
14| Skill loading | None | `load_skills[]` supported |
15| Model selection | From agent's fallback chain | From category config |
16| Use case | Quick contextual grep | Full delegation with skills |
17 
18## ALLOWED AGENTS
19 
20Only `explore` and `librarian` — enforced via `ALLOWED_AGENTS` constant in `constants.ts`. Case-insensitive validation.
21 
22## EXECUTION MODES
23 
24Same two modes as delegate-task:
25 
26| Mode | File | Description |
27|------|------|-------------|
28| **Background** | `background-agent-executor.ts` | Async via `BackgroundManager` |
29| **Sync** | `sync-executor.ts` | Create session → wait for idle → return result |
30 
31## KEY FILES
32 
33| File | Purpose |
34|------|---------|
35| `tools.ts` | `createCallOmoAgent()` factory — validates agent, routes to executor |
36| `background-executor.ts` | Routes to background or sync based on `run_in_background` |
37| `background-agent-executor.ts` | Launch via `BackgroundManager.launch()` |
38| `sync-executor.ts` | Synchronous session: create → send prompt → poll → fetch result |
39| `session-creator.ts` | Create OpenCode session for sync execution |
40| `subagent-session-creator.ts` | Create session with agent-specific config |
41| `subagent-session-prompter.ts` | Inject prompt into session |
42| `completion-poller.ts` | Poll until session idle |
43| `session-completion-poller.ts` | Session-specific completion check |
44| `session-message-output-extractor.ts` | Extract last assistant message as result |
45| `message-processor.ts` | Process raw message content |
46| `message-dir.ts` + `message-storage-directory.ts` | Temp storage for message exchange |
47| `types.ts` | `CallOmoAgentArgs`, `AllowedAgentType`, `ToolContextWithMetadata` |
48 
49## SESSION CONTINUATION
50 
51Pass `session_id` to resume an existing session rather than create a new one — handled in both executors.
52