[Feature]: Consume structured OMP subagent lifecycle hooks
- Dominant language
- TypeScript
- Stars
- 72.1k
- Forks
- 4.7k
- Avg merge
- 14h 54m
- Merged PRs (30d)
- 520
Description
## Problem or use case
OMP `task` workers run as in-process child agent sessions. Orca currently cannot reliably distinguish their lifecycle from the visible root OMP session, which can cause a child completion to mark the parent as finished (#9181) and can allow child prompt/message content to affect the parent preview (#9348). The generic agent-graph work is tracked by #8251, but it needs an OMP-specific, structured ingress contract before Orca can represent OMP children safely.
## Proposed solution
Add a versioned, authenticated OMP hook contract at the existing `/hook/omp` ingress that accepts child lifecycle records alongside normal root status records:
- `subagent_started`: stable child identity plus an optional opaque/display label.
- `subagent_finished`: the same identity plus a bounded terminal outcome (`completed`, `failed`, or `cancelled`).
- Every child record carries the parent/root session identity needed to attach it to the active pane/session.
The payload must be metadata-only: do not accept or persist prompts, tool arguments, assistant text, errors, or full child transcripts. Ingestion must be idempotent for duplicate start/finish events, reject/ignore child events that cannot be authenticated and routed to the current root session, and never let a child terminal event trigger the root-pane completion notification.
Expose these children through the existing agent hierarchy as nested rows under the root OMP session, with aggregate state in the root row. A child should be visible as working after start, terminal after finish, and never replace the root preview or create a second top-level OMP agent row.
## Alternatives or additional context
- This is a focused OMP adapter/ingress milestone for #8251, not a second generic graph API; it should link to the provider-neutral model when that model exists.
- #9181 and #9348 remain the correctness regressions this must not reintroduce.
- OMP currently needs a reliable public main/subagent identity surface. If that upstream contract is unavailable, do not infer children from PID, `yield`, UI presence, prompt text, or terminal output. Track the upstream dependency in can1357/oh-my-pi#5985.
- Acceptance evidence should include an end-to-end OMP `task` run in Orca: one root row, N nested child rows, no false root completion or preview overwrite, deduplicated repeated lifecycle hooks, and reconnect/restart cleanup consistent with #8251.
- The accompanying producer-only prototype is deliberately exploratory: it identifies candidate children from session IDs because OMP does not yet expose `agentKind`, `agentId`, `parentAgentId`, or `taskDepth` to extension lifecycle handlers. Its delivery was unit-tested only; it is not a substitute for the upstream identity contract and must not be shipped as a heuristic-based correctness fix.
Contributor guide
Assessment
This issue has not been assessed yet.