OpenCode native subagent tracking

[peyton-alt]

https://entire.io/gh/entireio/cli/trails/1316

Summary

• track OpenCode task tool subagents as durable task records on the parent session, one record per task call, with the child's exported transcript and exact token usage
• stop OpenCode child sessions from registering as top-level Entire sessions (they previously took the checkpoint while the parent logged "no files modified")
• two generic lifecycle changes: Event.DeferredCompletion records an in-flight marker at a fully-identified start, and event-files-only capture is keyed on SubagentTranscriptUnavailable rather than CompletionWithoutLaunch (Copilot sets both, so it is unchanged)
• research probe script and one-pager (cmd/entire/cli/agent/opencode/AGENT.md) capturing the verified OpenCode 1.18.30 contract

How it works

The embedded plugin learns child sessions from parentID on session.* events and from the parent's task-part metadata, and forwards no lifecycle hooks for them. It fires subagent-start from the parent's task part once it is running with state.metadata.sessionId, and subagent-stop synchronously from tool.execute.after. The Go adapter exports the child with opencode export, declares that file as the transcript, attaches its token usage, and emits a Final + CompletionWithoutLaunch SubagentEnd; the shared final capture extracts files from the declared transcript and completes the record exactly once. Condensation materializes tasks/<callID>/{task.json, agent-<child>.jsonl} under the parent checkpoint.

Verified

• Real OpenCode 1.18.30 sessions before the change (single, two concurrent children, read-only child): contract captured, and the bug reproduced every time.
• Real sessions with the candidate binary (google/gemini-2.5-flash-lite; the Anthropic key stored in OpenCode on this machine is rejected and Gemini Flash hit its free-tier quota): one Entire session, checkpoint on the parent titled with the user's prompt, tasks/<callID>/task.json + child transcript materialized, exact tokens, two concurrent children kept distinct with disjoint files.
• Unit, integration (TestOpenCodeSubagentTaskRecord), and Vogon canary pass. mise run lint clean.
• The paid OpenCode TestSubagentCommitFlow e2e now asserts a task record and a single session; not run in this PR.

Judgment call to confirm

Child sessions are suppressed plugin-side, so a user who opens a child session directly in the OpenCode TUI and drives it by hand is not tracked at all (no session, no task record). That is deliberate for v1 and documented in AGENT.md; flagging it here so a human can move it.

Known gaps

• Background subagents (OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS) are out of scope and ignored.
• Parent-level SubagentTokens aggregate is a follow-up; record-level tokens are exact.
• On macOS a child that spells a path through an unresolved symlink (/var/folders/... vs git's /private/var/...) is dropped from the record's files by the shared normalizer; the parent's turn-end still attributes the file. Agent-agnostic.
• A failed opencode export at stop time completes the record as transcript-unavailable; a lazy fetch at condensation is a follow-up.
• TestRunStatus_CheckpointPushDisabledDestinations fails on origin/main too (unrelated).
• Seven commits by implementer subagents carry a Claude Sonnet 5 co-author trailer; a squash merge normalizes it.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes checkpoint/session attribution for OpenCode subagents and shared subagent final-capture semantics; failures degrade to transcript-unavailable records rather than blocking the parent session.

Overview
Adds native OpenCode task subagent tracking so child sessions no longer become separate Entire sessions or steal checkpoints from the parent.

The embedded plugin (entire.ts) tracks childSessions from parentID and task metadata, suppresses all child lifecycle hooks (including context injection), and fires sync subagent-start (parent task part running with sessionId) and subagent-stop (tool.execute.after for foreground task).

The OpenCode Go adapter parses those hooks, sets DeferredCompletion on start and Final + CompletionWithoutLaunch on stop, **opencode export**s the child for transcript path and token usage, and validates subagent IDs.

Shared lifecycle gains recordDeferredTaskLaunch / Event.DeferredCompletion (in-flight task marker, no pre-task baseline) and keys event-files-only final capture on SubagentTranscriptUnavailable instead of CompletionWithoutLaunch so OpenCode can still scan a declared child export.

Docs, probe script, integration/e2e tests, and plugin template tests cover the contract.

^{Reviewed by Cursor Bugbot for commit a1bc976. Configure here.}

[Copilot]

🟡 Changes recommended

One critical and four moderate findings remain unresolved, along with a documentation nit.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds native OpenCode subagent tracking, preserving child transcripts and token usage as task records on the parent session.

Changes:

• Adds plugin hooks and child-session suppression.
• Exports transcripts and records exact token usage.
• Extends shared lifecycle handling for deferred and unavailable completions.
• Adds integration, E2E, documentation, and probe coverage.

Open findings: Critical (1 vote): process-wide call-ID guards can suppress new sessions. Moderate (1 vote): the embedded plugin has the same issue. Moderate (3 votes): staged export read failures can leave records incomplete. Moderate (1 vote): token-calculation failures have the same failure mode. Moderate (1 vote): resumed child sessions can produce cumulative per-call records. Nit (1 vote): documentation incorrectly promises recursive nested-task mapping.

File summaries

File	Reviewed change
e2e/tests/subagent_commit_flow_test.go	Verifies one parent session and materialized task records.
docs/architecture/sessions-and-checkpoints.md	Documents OpenCode task-record lifecycle.
docs/architecture/agent-guide.md	Updates agent lifecycle and transcript guidance.
cmd/entire/cli/lifecycle.go	Adds deferred task markers and transcript-aware final capture.
cmd/entire/cli/lifecycle_test.go	Tests deferred completion and declared-transcript capture.
cmd/entire/cli/integration_test/opencode_subagent_test.go	Covers native OpenCode task-record integration.
cmd/entire/cli/integration_test/hooks.go	Adds OpenCode subagent hook test helpers.
cmd/entire/cli/agent/opencode/types.go	Defines OpenCode hook and export payload types.
cmd/entire/cli/agent/opencode/lifecycle.go	Parses hooks, exports child transcripts, and attaches tokens.
cmd/entire/cli/agent/opencode/lifecycle_test.go	Tests OpenCode lifecycle and export behavior.
cmd/entire/cli/agent/opencode/hooks.go	Registers OpenCode lifecycle hooks.
cmd/entire/cli/agent/opencode/hooks_test.go	Tests plugin hook behavior.
cmd/entire/cli/agent/opencode/entire_plugin.ts	Tracks tasks and suppresses child sessions.
cmd/entire/cli/agent/event.go	Adds deferred-completion and transcript-availability fields.
.opencode/plugins/entire.ts	Updates the dogfood plugin implementation.

Review details

Suppressed comments (4)

cmd/entire/cli/agent/opencode/AGENT.md:163

• These lines claim nested task mapping is recursive, but the plugin returns early for every event whose session is already in childSessions; a task started by a child therefore emits no lifecycle hooks and cannot be mapped recursively. Please document nested subagents as currently suppressed/out of scope, or implement child-to-grandchild propagation before promising recursive support.

- **Nested subagents** are off by default (`subagent_depth: 1`); when enabled,
  `parentID` chains and the same mapping applies recursively.

cmd/entire/cli/agent/opencode/entire_plugin.ts:264

• announcedTasks is process-scoped and is only cleared on server disposal, but OpenCode callIDs are not globally unique. If a new parent session reuses a call ID from an earlier session, this guard suppresses its subagent-start, so no deferred/in-flight task record is created (the stop path can only reconstruct it later). Key this set by the parent session ID plus call ID, or clear it when switching parent sessions.

            if (part.type === "tool" && part.tool === "task" && part.callID &&
                part.state?.status === "running" && part.state?.metadata?.sessionId &&
                !announcedTasks.has(part.callID)) {
              announcedTasks.add(part.callID)
              childSessions.add(part.state.metadata.sessionId)

cmd/entire/cli/agent/opencode/lifecycle.go:265

• A token-calculation failure has the same incomplete-record failure mode as the read failure above: the declared transcript remains present, so final capture still attempts analysis and can fail rather than completing the task without token metadata. Set SubagentTranscriptUnavailable before returning so this path follows the documented fail-open behavior.

	usage, err := a.CalculateTokenUsage(data, 0)
	if err != nil {
		logging.Warn(logCtx, "opencode: could not compute subagent token usage",
			slog.String("subagent_id", event.SubagentID), slog.String("error", err.Error()))
		return

cmd/entire/cli/agent/opencode/lifecycle.go:254

• OpenCode's task_id resumption can reuse one child session across multiple call IDs, but this path exports from the beginning and calculates tokens from offset zero. A later call therefore receives the cumulative earlier transcript/files and token total under a new task record, which is not exact per-call tracking. Please either slice export and token usage at the call boundary or model the reused child as one multi-turn record rather than advertising one exact record per call.

	path, err := a.fetchAndCacheExport(ctx, event.SubagentID)
	if err != nil {
		logging.Warn(logCtx, "opencode: could not export subagent transcript; completing task without it",
			slog.String("session_id", event.SessionID),
			slog.String("tool_use_id", event.ToolUseID),
			slog.String("subagent_id", event.SubagentID),
			slog.String("error", err.Error()))
		event.SubagentTranscriptUnavailable = true
		return
	}
	event.SubagentTranscriptPath = path

• Files reviewed: 17/17 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.