oh-my-opencode 4.8.1 → 4.9.1

package/packages/omo-codex/plugin/skills/lsp-setup/scripts/lsp-server-table.ts

@@ -0,0 +1,177 @@
+// SOURCE OF TRUTH: packages/lsp-tools-mcp/src/lsp/server-definitions.ts
+// (BUILTIN_SERVERS + LSP_INSTALL_HINTS). This is a hand-maintained snapshot of
+// the primary builtin server per reference language, embedded so detect-lsp.ts
+// runs standalone in any user project. Mirror command/extensions when that file
+// changes.
+
+export interface LanguageServer {
+	readonly language: string
+	readonly serverId: string
+	readonly command: readonly string[]
+	readonly extensions: readonly string[]
+	readonly installHint: string
+}
+
+export const LANGUAGES: readonly LanguageServer[] = [
+	{
+		language: "typescript",
+		serverId: "typescript",
+		command: ["typescript-language-server", "--stdio"],
+		extensions: [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"],
+		installHint: "npm install -g typescript-language-server typescript",
+	},
+	{
+		language: "python",
+		serverId: "basedpyright",
+		command: ["basedpyright-langserver", "--stdio"],
+		extensions: [".py", ".pyi"],
+		installHint: "pip install basedpyright (or: uv tool install basedpyright)",
+	},
+	{
+		language: "go",
+		serverId: "gopls",
+		command: ["gopls"],
+		extensions: [".go"],
+		installHint: "go install golang.org/x/tools/gopls@latest",
+	},
+	{
+		language: "rust",
+		serverId: "rust",
+		command: ["rust-analyzer"],
+		extensions: [".rs"],
+		installHint: "rustup component add rust-analyzer",
+	},
+	{
+		language: "c-cpp",
+		serverId: "clangd",
+		command: ["clangd", "--background-index", "--clang-tidy"],
+		extensions: [".c", ".cpp", ".cc", ".cxx", ".c++", ".h", ".hpp", ".hh", ".hxx", ".h++"],
+		installHint: "macOS: brew install llvm | Linux: apt install clangd | https://clangd.llvm.org/installation",
+	},
+	{
+		language: "java",
+		serverId: "jdtls",
+		command: ["jdtls"],
+		extensions: [".java"],
+		installHint: "macOS: brew install jdtls | https://github.com/eclipse-jdtls/eclipse.jdt.ls",
+	},
+	{
+		language: "kotlin",
+		serverId: "kotlin-ls",
+		command: ["kotlin-lsp"],
+		extensions: [".kt", ".kts"],
+		installHint: "https://github.com/Kotlin/kotlin-lsp",
+	},
+	{
+		language: "csharp",
+		serverId: "csharp",
+		command: ["csharp-ls"],
+		extensions: [".cs"],
+		installHint: "dotnet tool install -g csharp-ls",
+	},
+	{
+		language: "razor",
+		serverId: "razor",
+		command: ["roslyn-language-server", "--stdio"],
+		extensions: [".razor", ".cshtml"],
+		installHint: "dotnet tool install -g roslyn-language-server --prerelease (see references/csharp/README.md)",
+	},
+	{
+		language: "swift",
+		serverId: "sourcekit-lsp",
+		command: ["sourcekit-lsp"],
+		extensions: [".swift", ".objc", ".objcpp"],
+		installHint: "Included with Xcode (xcode-select --install) or the Swift toolchain",
+	},
+	{
+		language: "ruby",
+		serverId: "ruby-lsp",
+		command: ["rubocop", "--lsp"],
+		extensions: [".rb", ".rake", ".gemspec", ".ru"],
+		installHint: "gem install ruby-lsp (builtin runs `rubocop --lsp`; gem install rubocop)",
+	},
+	{
+		language: "php",
+		serverId: "php",
+		command: ["intelephense", "--stdio"],
+		extensions: [".php"],
+		installHint: "npm install -g intelephense",
+	},
+	{
+		language: "dart",
+		serverId: "dart",
+		command: ["dart", "language-server", "--lsp"],
+		extensions: [".dart"],
+		installHint: "Included with the Dart/Flutter SDK",
+	},
+	{
+		language: "elixir",
+		serverId: "elixir-ls",
+		command: ["elixir-ls"],
+		extensions: [".ex", ".exs"],
+		installHint: "https://github.com/elixir-lsp/elixir-ls",
+	},
+	{
+		language: "zig",
+		serverId: "zls",
+		command: ["zls"],
+		extensions: [".zig", ".zon"],
+		installHint: "https://github.com/zigtools/zls (match zls version to your zig version)",
+	},
+	{
+		language: "lua",
+		serverId: "lua-ls",
+		command: ["lua-language-server"],
+		extensions: [".lua"],
+		installHint: "macOS: brew install lua-language-server | https://github.com/LuaLS/lua-language-server",
+	},
+	{
+		language: "bash",
+		serverId: "bash",
+		command: ["bash-language-server", "start"],
+		extensions: [".sh", ".bash", ".zsh", ".ksh"],
+		installHint: "npm install -g bash-language-server",
+	},
+	{
+		language: "yaml",
+		serverId: "yaml-ls",
+		command: ["yaml-language-server", "--stdio"],
+		extensions: [".yaml", ".yml"],
+		installHint: "npm install -g yaml-language-server",
+	},
+	{
+		language: "terraform",
+		serverId: "terraform",
+		command: ["terraform-ls", "serve"],
+		extensions: [".tf", ".tfvars"],
+		installHint: "macOS: brew install hashicorp/tap/terraform-ls | https://github.com/hashicorp/terraform-ls",
+	},
+	{
+		language: "dockerfile",
+		serverId: "dockerfile",
+		command: ["docker-langserver", "--stdio"],
+		extensions: [".dockerfile"],
+		installHint: "npm install -g dockerfile-language-server-nodejs",
+	},
+	{
+		language: "haskell",
+		serverId: "haskell-language-server",
+		command: ["haskell-language-server-wrapper", "--lsp"],
+		extensions: [".hs", ".lhs"],
+		installHint: "ghcup install hls",
+	},
+	{
+		language: "julia",
+		serverId: "julials",
+		command: ["julia", "--startup-file=no", "--history-file=no", "-e", "using LanguageServer; runserver()"],
+		extensions: [".jl"],
+		installHint: "julia -e 'using Pkg; Pkg.add(\"LanguageServer\")' (see references/julia/README.md)",
+	},
+] as const
+
+export const PROJECT_CONFIG_FILES: readonly string[] = [
+	".codex/lsp-client.json",
+	".opencode/lsp.json",
+	".omo/lsp.json",
+	".omo/lsp-client.json",
+] as const

package/packages/omo-codex/plugin/skills/lsp-setup/scripts/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "lib": ["ESNext"],
+    "types": ["bun-types"]
+  },
+  "include": ["*.ts"]
+}

package/packages/omo-codex/plugin/skills/lsp-setup/scripts/verify-lsp.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+// verify-lsp.ts <file> [--timeout=ms] — perform a real LSP diagnostics roundtrip
+// for <file> through the lsp-tools-mcp engine and report ok/fail with error text.
+// The engine source is located by walking up from this script and the cwd, so
+// run it inside the omo repo/worktree (where packages/lsp-tools-mcp/src exists).
+
+import { existsSync, statSync } from "node:fs"
+import { dirname, isAbsolute, join, resolve } from "node:path"
+import process from "node:process"
+import { fileURLToPath, pathToFileURL } from "node:url"
+
+const ENGINE_TOOLS = "packages/lsp-tools-mcp/src/tools.ts"
+const ENGINE_CONTEXT = "packages/lsp-tools-mcp/src/request-context.ts"
+const ENGINE_MANAGER = "packages/lsp-tools-mcp/src/lsp/manager.ts"
+const DEFAULT_TIMEOUT_MS = 60_000
+
+interface ToolExecutionResult {
+	readonly content: ReadonlyArray<{ readonly type: "text"; readonly text: string }>
+	readonly isError?: boolean
+	readonly details?: unknown
+}
+
+interface DiagnosticsDetails {
+	readonly mode: "file" | "directory"
+	readonly totalDiagnostics: number
+	readonly error?: string
+	readonly errorKind?: "missing_dependency" | "no_files" | "invalid_path"
+}
+
+interface ToolsModule {
+	readonly executeLspDiagnostics: (params: Record<string, unknown>, signal?: AbortSignal) => Promise<ToolExecutionResult>
+}
+
+interface ContextModule {
+	readonly runWithRequestContext: <T>(context: { cwd?: string; env?: Record<string, string> }, fn: () => T) => T
+}
+
+interface ManagerModule {
+	readonly disposeDefaultLspManager: () => Promise<void>
+}
+
+function findUp(relativeTarget: string): string | null {
+	const starts = [dirname(fileURLToPath(import.meta.url)), process.cwd()]
+	for (const start of starts) {
+		let current = start
+		while (true) {
+			const candidate = join(current, relativeTarget)
+			if (existsSync(candidate)) return candidate
+			const parent = dirname(current)
+			if (parent === current) break
+			current = parent
+		}
+	}
+	return null
+}
+
+function buildEnv(): Record<string, string> {
+	const env: Record<string, string> = {}
+	for (const [key, value] of Object.entries(process.env)) {
+		if (value !== undefined) env[key] = value
+	}
+	return env
+}
+
+function isDiagnosticsDetails(value: unknown): value is DiagnosticsDetails {
+	return typeof value === "object" && value !== null && "mode" in value && "totalDiagnostics" in value
+}
+
+async function loadModule<T>(relativeTarget: string): Promise<T> {
+	const path = findUp(relativeTarget)
+	if (path === null) {
+		throw new EngineNotFoundError(relativeTarget)
+	}
+	return (await import(pathToFileURL(path).href)) as T
+}
+
+class EngineNotFoundError extends Error {
+	constructor(public readonly target: string) {
+		super(`lsp-tools-mcp engine not found (looked for ${target}). Run verify-lsp.ts inside the omo repo/worktree.`)
+		this.name = "EngineNotFoundError"
+	}
+}
+
+function parseTimeout(args: readonly string[]): number {
+	const flag = args.find((arg) => arg.startsWith("--timeout="))
+	if (flag === undefined) return DEFAULT_TIMEOUT_MS
+	const parsed = Number.parseInt(flag.slice("--timeout=".length), 10)
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_TIMEOUT_MS
+}
+
+async function run(filePath: string, timeoutMs: number): Promise<number> {
+	const tools = await loadModule<ToolsModule>(ENGINE_TOOLS)
+	const context = await loadModule<ContextModule>(ENGINE_CONTEXT)
+	const manager = await loadModule<ManagerModule>(ENGINE_MANAGER)
+	const absolute = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath)
+
+	try {
+		const signal = AbortSignal.timeout(timeoutMs)
+		const result = await context.runWithRequestContext({ cwd: process.cwd(), env: buildEnv() }, () =>
+			tools.executeLspDiagnostics({ filePath: absolute, severity: "all" }, signal),
+		)
+		const details = isDiagnosticsDetails(result.details) ? result.details : null
+		const text = result.content.map((part) => part.text).join("\n")
+
+		if (details?.errorKind === "missing_dependency") {
+			process.stdout.write(`FAIL ${absolute}: language server not installed\n${text}\n`)
+			return 1
+		}
+		if (result.isError === true || details?.errorKind === "invalid_path" || details?.errorKind === "no_files") {
+			process.stdout.write(`FAIL ${absolute}: ${details?.error ?? text}\n`)
+			return 1
+		}
+
+		const count = details?.totalDiagnostics ?? 0
+		process.stdout.write(`OK ${absolute}: LSP roundtrip succeeded (${count} diagnostic(s))\n${text}\n`)
+		return 0
+	} finally {
+		await manager.disposeDefaultLspManager()
+	}
+}
+
+async function main(): Promise<void> {
+	const args = process.argv.slice(2)
+	const filePath = args.find((arg) => !arg.startsWith("--"))
+	if (filePath === undefined) {
+		process.stderr.write("Usage: bun verify-lsp.ts <file> [--timeout=ms]\n")
+		process.exit(2)
+	}
+	if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+		process.stderr.write(`verify-lsp: not a file: ${filePath}\n`)
+		process.exit(2)
+	}
+
+	try {
+		const code = await run(filePath, parseTimeout(args))
+		process.exit(code)
+	} catch (error) {
+		if (error instanceof EngineNotFoundError) {
+			process.stderr.write(`SKIP: ${error.message}\n`)
+			process.exit(3)
+		}
+		process.stderr.write(`FAIL ${filePath}: ${error instanceof Error ? error.message : String(error)}\n`)
+		process.exit(1)
+	}
+}
+
+await main()

package/packages/omo-codex/plugin/skills/refactor/SKILL.md

@@ -9,17 +9,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
-| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"codex-ultrawork-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
 
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, and `codex-ultrawork-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 export const REFACTOR_TEMPLATE = `# Intelligent Refactor Command
 

package/packages/omo-codex/plugin/skills/remove-ai-slops/SKILL.md

@@ -9,17 +9,17 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
-| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"codex-ultrawork-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
 
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, and `codex-ultrawork-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
 
-For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `wait_agent` timeout only means no new mailbox update arrived. Treat a running child or latest `WORKING:` message as alive. Do not use `list_agents` as a polling loop. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 # Remove AI Slops Skill
 
@@ -211,7 +211,7 @@ For each skipped issue, give reason.
 )
 ```
 
-**Batch failure handling**: a `wait_agent` timeout only means no new mailbox update arrived, not that a `deep` agent failed. For long passes, require each child to send `WORKING: <file> - <current phase>` and `BLOCKED: <reason>` only when it cannot progress. If you need reassurance after a timeout, run a single `list_agents` check for the named child; a running child or latest `WORKING:` message is alive. Mark a file for retry only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Do NOT block the remaining 4 in that batch; collect successful results and retry the failed file once later. If retry also fails, escalate that file under "Issues Found & Fixed" in the final report.
+**Batch failure handling**: a `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived, not that a `deep` agent failed. For long passes, require each child to send `WORKING: <file> - <current phase>` and `BLOCKED: <reason>` only when it cannot progress. Treat a running child as alive. Mark a file for retry only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running. Do NOT block the remaining 4 in that batch; collect successful results and retry the failed file once later. If retry also fails, escalate that file under "Issues Found & Fixed" in the final report.
 
 ### Phase 5: Verify with quality gates + critical review
 

package/packages/omo-codex/plugin/skills/review-work/SKILL.md

@@ -8,27 +8,28 @@ This skill may include examples copied from the OpenCode harness. In Codex, do n
 
 | OpenCode example | Codex tool to use |
 | --- | --- |
-| `call_omo_agent(subagent_type="explore", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as an explorer. ...","fork_turns":"none"})` |
-| `call_omo_agent(subagent_type="librarian", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a librarian. ...","fork_turns":"none"})` |
-| `task(subagent_type="plan", ...)` | `spawn_agent({"task_name":"...","message":"TASK: act as a planning agent. ...","fork_turns":"none"})` |
-| `task(subagent_type="oracle", ...)` for final verification | `spawn_agent({"task_name":"...","message":"TASK: act as a rigorous reviewer. ...","fork_turns":"none"})` |
-| `task(category="...", ...)` for implementation or QA | `spawn_agent({"task_name":"...","message":"TASK: act as an implementation or QA worker. ...","fork_turns":"none"})` |
-| `background_output(task_id="...")` | `wait_agent(...)` for mailbox signals; after a timeout, run one `list_agents` check for the named child if reassurance is needed |
-| `team_*(...)` | Use Codex native subagents plus `send_message`, `followup_task`, `wait_agent`, and `close_agent` |
+| `call_omo_agent(subagent_type="explore", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as an explorer. ...","agent_type":"explorer","fork_context":false})` |
+| `call_omo_agent(subagent_type="librarian", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a librarian. ...","agent_type":"librarian","fork_context":false})` |
+| `task(subagent_type="plan", ...)` | `multi_agent_v1.spawn_agent({"message":"TASK: act as a planning agent. ...","agent_type":"plan","fork_context":false})` |
+| `task(subagent_type="oracle", ...)` for final verification | `multi_agent_v1.spawn_agent({"message":"TASK: act as a rigorous reviewer. ...","agent_type":"codex-ultrawork-reviewer","fork_context":false})` |
+| `task(category="...", ...)` for implementation or QA | `multi_agent_v1.spawn_agent({"message":"TASK: act as an implementation or QA worker. ...","fork_context":false})` |
+| `background_output(task_id="...")` | `multi_agent_v1.wait_agent(...)` for mailbox signals |
+| `team_*(...)` | Use Codex native subagents via `multi_agent_v1.spawn_agent`, `multi_agent_v1.send_input`, `multi_agent_v1.wait_agent`, and `multi_agent_v1.close_agent` |
 
-Codex full-history forks inherit parent context, so role-specific behavior must be described in a self-contained `message` and usually should use a non-full-history fork mode such as `fork_turns="none"`. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. If a code block below conflicts with this section, this section wins.
+Role-specific behavior must be described in a self-contained `message`. Use `fork_context: false` to start the child with only the initial prompt (no parent history); use `fork_context: true` only when full parent history is truly required. Include any required conversation context, files, diffs, constraints, and requested skill names directly in the spawned agent's `message`. OMO installs these selectable agent roles into `~/.codex/agents/`: `explorer`, `librarian`, `plan`, `momus`, `metis`, and `codex-ultrawork-reviewer` — pass the matching name as `agent_type` so the child gets that role's model and instructions. On `multi_agent_v2` sessions the same `agent_type` applies (the OMO installer exposes it) with `fork_turns` instead of `fork_context`. If the spawn tool exposes no `agent_type` parameter, omit it and describe the role inside `message`. If a code block below conflicts with this section, this section wins.
+
+For work likely to exceed one wait cycle, require the child to send `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A `multi_agent_v1.wait_agent` timeout only means no new mailbox update arrived. Treat a running child as alive. Fallback only when the child is completed without the deliverable, ack-only after followup, explicitly `BLOCKED:`, or no longer running.
 
 ## Codex Subagent Reliability
 
-Every `spawn_agent` message must be self-contained. Start with
+Every `multi_agent_v1.spawn_agent` message must be self-contained. Start with
 `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and
 `VERIFY`. State that it is an executable assignment, not a context
-handoff. Role or specialty instructions belong inside `message`; the
-Codex tool schema only accepts `task_name`, `message`, and `fork_turns`.
-Prefer `fork_turns: "none"` unless full history is truly
+handoff. Role or specialty instructions belong inside `message`.
+Use `fork_context: false` unless full history is truly
 required; paste only the review context that worker needs.
 
-Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short wait_agent cycles sized to the work. Never use a single long blocking wait for them, and never spin on tiny timeouts as a failure budget.
+Plan and reviewer agents may run for a long time; spawn them in the background, keep doing independent root work, and poll with short `multi_agent_v1.wait_agent` cycles sized to the work. Never use a single long blocking wait for them, and never spin on tiny timeouts as a failure budget.
 
 Treat child status as a progress signal, not a timeout counter. For
 work likely to exceed one wait cycle, require the child to send
@@ -37,16 +38,13 @@ review passes, and `BLOCKED: <reason>` only when it cannot progress.
 While any child is active, keep the parent visibly alive with active
 subagent count, agent names, latest `WORKING:` phase, and whether the
 parent is waiting for mailbox updates. Track spawned agent names
-locally. Use `wait_agent` for mailbox signals, not proof of completion.
-A timeout only means no new mailbox update arrived; after a timeout,
-run a single `list_agents` check for the named child when you need
-reassurance. If it is running or its latest message is `WORKING:`,
-treat it as alive. Do not use `list_agents` as a polling loop or status
-feed; it can replay large payloads. Fallback only when the child is
+locally. Use `multi_agent_v1.wait_agent` for mailbox signals, not proof of completion.
+A timeout only means no new mailbox update arrived. Treat a running child as alive.
+Fallback only when the child is
 completed without the deliverable, ack-only after followup, explicitly
 `BLOCKED:`, or no longer running. Then mark that review lane
 `INCONCLUSIVE`, do not count it as PASS or approval, close if safe, and
-respawn a smaller `fork_turns: "none"` reviewer with the missing
+respawn a smaller `fork_context: false` reviewer with the missing
 deliverable. Preserve completed lane results immediately. If the retry
 budget is exhausted, keep the lane `INCONCLUSIVE` and still emit a final
 aggregate result.
@@ -543,7 +541,7 @@ After launching all 5 agents in one turn, wait for completions in bounded
 cycles. Do not treat a timeout, ack-only reply, or empty child result as
 a PASS.
 
-As each completes, collect via the Codex mapping above (`wait_agent`,
+As each completes, collect via the Codex mapping above (`multi_agent_v1.wait_agent`,
 then the child's substantive final result). Preserve completed lane
 results immediately; never lose a PASS/FAIL because another lane is
 still running. Store each verdict independently:
@@ -563,7 +561,7 @@ inconclusive and respawn a smaller reviewer/worker for that exact lane.
 If it still remains unfinished after that retry, close the still-running
 agent if safe, keep the lane INCONCLUSIVE, and emit the final aggregate
 review result with the incomplete lane named. Do not spin in repeated
-wait/followup cycles. Do not use `send_message` as an interrupt; queued
+wait/followup cycles. Do not use `multi_agent_v1.send_input` as an interrupt; queued
 followups are not cancellation.
 
 ---