oc-subagent

# oc-subagent ## Overview Use this skill when a project agent needs a simple, direct OpenCode serve MVP for subagents: one parent session, stable logical subagent ids, child sessions for executors, blocking turn completion, and proof artifacts. Prefer this skill over hand-written OpenCode endpoint logic. This skill intentionally stays below the full `$scillm` transport/orchestrator layer. Use `$scillm` transport when the work needs durable DAG state, retries, validation gates, amendment, or UI steering. Use `$oc-subagent` when the immediate question is whether OpenCode child sessions can run concurrently and preserve state across turns. ## Core Invariants 1. Create exactly one parent OpenCode session for the test run unless explicitly recovering from failure. 2. Create one child session per logical subagent using `parentID`. 3. Track a stable logical id such as `subagent_1` separately from the physical `child_session_id`. 4. Reuse the same child session for repeated turns to the same logical subagent. 5. Serialize turns sent to the same `subagent_run_id`. 6. Dispatch independent `subagent_run_id`s concurrently only when they use different child sessions. 7. Never advance a dependent task based only on prompt dispatch or partial SSE output. 8. Advance only after the turn returns a terminal HTTP response or equivalent terminal run status and the result validates. 9. Persist session maps, request/response artifacts, raw SSE, normalized JSONL events, heartbeats, task status, child listings, message listings, and final proof JSON. 10. A persistence prompt must not leak the prior result or its ingredients (the turn-2 prompt uses no digits). 11. Prove session memory with a negative control: the same turn-2 prompt sent to a fresh child session that never ran turn 1 must not produce the persisted answer. 12. Derive proof booleans from recorded timestamps and prompt scans, never hard-code them. ## Session Model ```text project_agent_run_id └── parent_session_id ├── child_session_id for subagent_1 ├── child_session_id for subagent_2 └── child_session_id for subagent_3 ``` The project agent should reason in logical ids: ```text subagent_1 subagent_2 subagent_3 ``` The skill user maps those to physical OpenCode ids: ```json { "run_id": "oc-subagent-persistence-001", "parent_session_id": "ses_parent", "subagents": { "subagent_1": {"child_session_id": "ses_child_a"}, "subagent_2": {"child_session_id": "ses_child_b"}, "subagent_3": {"child_session_id": "ses_child_c"} } } ``` ## Minimal MVP Probe Use this task list to prove persistence and concurrency without `$scillm` transport overhead: ```text 1. Project agent computes 2 + 2 = 4. 2. subagent_1 turn 1: "Compute 3 * 6, then add the project-agent previous result, which is 4. Store the resulting number as last_result." Expected: 22 3. In parallel: subagent_2: "What is the capital of France?" Expected: Paris subagent_3: "In simple everyday examples, what color is most commonly associated with an apple?" Expected: red 4. Wait for both subagent_2 and subagent_3 to finish. 5. subagent_1 turn 2 (same child session, value not restated): "Add ten to your last_result from this same session." Expected: 32 6. Negative control (fresh child session, no turn 1): Send the turn-2 prompt to a brand-new child session that never ran turn 1. Expected: it must NOT produce 32 (it has no last_result to recall). ``` The turn-2 `subagent_1` prompt must not contain `22`, `18`, `4`, or `32`; it uses the word "ten" and contains no digits. If it does, the test proves prompt leakage, not session persistence. If the negative-control session produces `32` anyway, the `32` from the real run is not trustworthy evidence of session memory and the proof fails. ## Direct OpenCode Serve Calls Prefer a local OpenCode serve instance: ```bash export OPENCODE_BASE="${OPENCODE_BASE:-http://127.0.0.1:4096}" export OC_AGENT="${OC_AGENT:-build}" export OC_MODEL="${OC_MODEL:-}" export RUN_ID="${RUN_ID:-oc-subagent-persistence-$(date +%Y%m%dT%H%M%S)}" export ARTIFACT_DIR="${ARTIFACT_DIR:-./artifacts/$RUN_ID}" mkdir -p "$ARTIFACT_DIR" ``` Use OpenCode agent profiles such as `build`, `plan`, `general`, or configured local profiles. Do not put chat model ids such as `opencode-go/kimi-k2.6` in the OpenCode `agent` field. For this MVP proof, prefer a cheap model because the questions are simple and the proof target is child-session behavior. The live runner auto-selects a model unless `OC_MODEL` is set: 1. Local/free Ollama Qwen models, preferring `ollama/qwen3:14b` when present, then available local Qwen variants such as `ollama/qwen3:8b-nothink`, `ollama/qwen3:8b`, or `ollama/qwen2.5:14b`. 2. Cheap OpenCode Go fallback, currently `opencode-go/kimi-k2.6`. 3. Paid/high-confidence fallback, currently `openai/gpt-5.5`. `OC_MODEL` is sent as the message `model` object; it is not the `agent` profile. Set `OC_MODEL_CANDIDATES` to a comma-separated list to override the auto-selection order. Set `OC_OLLAMA_MODEL` to prefer a specific local Ollama tag. The selected model and rejected candidates are written to `model-selection.json`. Use different models for different work: | Work type | Default model policy | |-----------|----------------------| | Cheap MVP persistence/concurrency proof | Local Ollama Qwen first, then OpenCode Go | | Design critique, information architecture, broad synthesis | Moonshot AI Kimi K2.6 when configured, or OpenCode Go Kimi K2.6 | | Coding, debugging, patch planning, hard correctness gates | GPT-5.5 high reasoning via OAuth/profile only when the task needs it | Do not spend GPT-5.5 high reasoning on this MVP sanity unless cheaper candidates fail or the runner is diagnosing a real substrate bug. ## Live Sanity Run the real MVP task list against a local OpenCode serve sidecar: ```bash OPENCODE_BASE=http://127.0.0.1:4098 \ ARTIFACT_DIR=/tmp/oc-subagent/live-proof-$(date +%Y%m%dT%H%M%S) \ ./sanity-live.sh ``` Expected success output: ```json { "verdict": "PASS", "artifact_dir": "/tmp/oc-subagent/live-proof-..." } ``` If OpenCode is unreachable, the script writes `proof.json` with `verdict: BLOCKED`. If a task answer, session id, concurrency, or prompt-leak invariant fails, it writes `verdict: FAIL`. Minimal helpers: ```bash oc_json_id() { jq -r '.id // .ID // .sessionID // .session_id // empty' } oc_message_body() { local text="$1" jq -n --arg agent "$OC_AGENT" --arg text "$text" \ '{agent: $agent, parts: [{type: "text", text: $text}]}' } oc_create_parent() { local title="$1" curl -sS -X POST "$OPENCODE_BASE/session" \ -H 'Content-Type: application/json' \ -d "$(jq -n --arg title "$title" '{title: $title}')" } oc_create_child() { local parent_id="$1" local title="$2" curl -sS -X POST "$OPENCODE_BASE/session" \ -H 'Content-Type: application/json' \ -d "$(jq -n --arg parentID "$parent_id" --arg title "$title" '{parentID: $parentID, title: $title}')" } oc_send_turn_and_wait() { local child_session_id="$1" local text="$2" curl -sS -X POST "$OPENCODE_BASE/session/$child_session_id/message" \ -H 'Content-Type: application/json' \ -d "$(oc_message_body "$text")" } ``` ## Evidence Contract Write artifacts under one run directory: ```text artifacts/<run_id>/ project-agent-state.json parent-session.json session-map.json events.sse subagent_1-session.json subagent_1-turn-1-request.txt subagent_1-turn-1-response.json subagent_1-turn-2-request.txt subagent_1-turn-2-response.json subagent_2-session.json subagent_2-concurrent-request.txt subagent_2-concurrent-response.json subagent_3-session.json subagent_3-concurrent-request.txt subagent_3-concurrent-response.json subagent_1_negative-session.json subagent_1_negative-request.txt subagent_1_negative-response.json children-after.json messages-subagent_1-after.json model-selection.json events.jsonl heartbeats.jsonl timeline.jsonl task-status.json proof.json ``` Final proof shape: ```json { "verdict": "PASS", "run_id": "oc-subagent-persistence-001", "parent_session_id": "ses_parent", "model_selection": { "selected_model": "ollama/qwen3:8b-nothink", "artifact": "model-selection.json" }, "project_agent_persistence": { "step_1_result": 4, "state_survived_unrelated_tasks": true }, "sequential_subagent_persistence": { "subagent_run_id": "subagent_1", "child_session_id_turn_1": "ses_child_a", "child_session_id_turn_2": "ses_child_a", "same_child_session": true, "turn_1_answer": 22, "turn_2_answer": 32, "turn_2_prompt_did_not_leak_prior_value": true, "turn_2_waited_for_turn_1": true, "passed": true }, "concurrent_subagents": { "subagent_2_child_session_id": "ses_child_b", "subagent_3_child_session_id": "ses_child_c", "subagent_2_answer": "Paris", "subagent_3_answer": "red", "both_dispatched_before_first_result_consumed": true, "passed": true }, "negative_control": { "subagent_run_id": "subagent_1_negative", "child_session_id": "ses_child_neg", "prompt_is_turn_2_without_turn_1": true, "answer": null, "produced_32": false, "passed": true }, "failure_reasons": [], "artifacts": { "model_selection": "model-selection.json", "session_map": "session-map.json", "events": "events.sse", "events_jsonl": "events.jsonl", "heartbeats": "heartbeats.jsonl", "timeline": "timeline.jsonl", "task_status": "task-status.json", "children_after": "children-after.json", "messages_subagent_1_after": "messages-subagent_1-after.json", "negative_control_session": "subagent_1_negative-session.json", "negative_control_response": "subagent_1_negative-response.json" } } ``` ## Observability Contract The live runner follows the scillm transport convention: raw SSE is preserved for forensics, normalized JSONL is written for machines, and task state is snapshotted for operators. ```text events.sse raw OpenCode event stream events.jsonl normalized SSE rows keyed by session/subagent when known timeline.jsonl project-agent lifecycle rows such as run_started, task_started, task_completed heartbeats.jsonl periodic liveness rows for active DAG nodes/subagent calls task-status.json latest per-node state snapshot ``` Completion still gates on a terminal message response plus result validation. Heartbeats and streamed deltas prove liveness and diagnosability; they are not sufficient by themselves to advance a dependent DAG node. ## Failure Conditions Fail the proof if any of these occur: - `subagent_1` turn 2 uses a different child session without an explicit fork/recovery receipt. - Turn 2 dispatches before turn 1 returned and validated. - Two simultaneous turns are sent to the same child session. - Concurrent distractor results are consumed before both independent calls were dispatched. - The turn-2 `subagent_1` prompt includes `22`, `18`, `4`, or `32`. - The negative-control session (turn-2 prompt, no turn 1) produces `32`, which would mean `32` is not proof of session memory. - A measured invariant (`turn_2_prompt_did_not_leak_prior_value`, `turn_2_waited_for_turn_1`, `both_dispatched_before_first_result_consumed`) is false rather than asserted true. - The proof is based only on natural-language claims rather than saved artifacts. - A chat model id is used as the OpenCode `agent` field. - `events.jsonl`, `heartbeats.jsonl`, `timeline.jsonl`, or `task-status.json` is missing from a live run. ## Output Summary Return a concise final summary: ```text VERDICT: PASS | FAIL Project-agent state: PASS | FAIL Sequential subagent persistence: PASS | FAIL Concurrent subagents: PASS | FAIL Final values: project_agent_step_1 = 4 subagent_1_final = 32 subagent_2 = Paris subagent_3 = red Artifact directory: artifacts/<run_id> ```