|
| 1 | +# t1305: OpenCode Upstream Issue Draft |
| 2 | + |
| 3 | +**Upstream issue created:** https://github.com/anomalyco/opencode/issues/14691 |
| 4 | + |
| 5 | +## Target Repository |
| 6 | + |
| 7 | +`anomalyco/opencode` (108k+ stars) |
| 8 | + |
| 9 | +## Issue Title |
| 10 | + |
| 11 | +`[FEATURE]: Plugin hooks for streaming token observation (stream.delta) and abort handling (stream.aborted)` |
| 12 | + |
| 13 | +## Research Summary |
| 14 | + |
| 15 | +### Existing Related Issues (no direct overlap) |
| 16 | + |
| 17 | +| Issue | Title | Relevance | |
| 18 | +|-------|-------|-----------| |
| 19 | +| #9737 | Expose partial tool arguments during streaming via state.raw | Identifies the exact `tool-input-delta: break` no-op in `processor.ts`. Focuses on UI state, not plugin hooks. | |
| 20 | +| #13524 | Refactor: centralize tool plugin hooks + add agent to hook input | Centralizes existing hooks, doesn't add streaming hooks. | |
| 21 | +| #12472 | Native Claude Code hooks compatibility (PreToolUse, PostToolUse, Stop) | Maps Claude Code hooks to OpenCode events. No streaming-level hooks. | |
| 22 | +| #14451 | Ability to intercept or emulate agent messages in plugins | Message interception, not token-level streaming. | |
| 23 | +| #10374 | Allow "aborted" agents to be continued | Abort recovery for subagents, not streaming abort. | |
| 24 | +| #8197 | Add retry/re-run capability when operation is aborted | UI retry button, not programmatic abort handling. | |
| 25 | +| #13809 | Preserve partial bash output for the model after abort | Partial output preservation, not plugin hooks. | |
| 26 | + |
| 27 | +### Key Finding |
| 28 | + |
| 29 | +The `processor.ts` streaming loop (line ~120) has explicit no-ops for `tool-input-delta` and `tool-input-end`: |
| 30 | + |
| 31 | +```typescript |
| 32 | +case "tool-input-delta": |
| 33 | + break // Delta discarded |
| 34 | +case "tool-input-end": |
| 35 | + break // Completion ignored |
| 36 | +``` |
| 37 | + |
| 38 | +The `text-delta` case accumulates text but has no plugin hook (only `text-end` triggers `experimental.text.complete`). |
| 39 | + |
| 40 | +No existing issue proposes plugin hooks at the streaming token level. |
| 41 | + |
| 42 | +### Existing Hook System |
| 43 | + |
| 44 | +The `Hooks` interface in `packages/plugin/src/index.ts` follows a consistent pattern: |
| 45 | +- Input: context object (sessionID, messageID, etc.) |
| 46 | +- Output: mutable object the hook can modify |
| 47 | +- Triggered via `Plugin.trigger(name, input, output)` |
| 48 | + |
| 49 | +Current hooks: `chat.message`, `chat.params`, `tool.execute.before/after`, `experimental.text.complete`, etc. |
| 50 | + |
| 51 | +## Motivation (from oh-my-pi benchmark data) |
| 52 | + |
| 53 | +Can Boluk's "The Harness Problem" (2026-02-12) demonstrated that harness engineering is the highest-leverage optimization available: |
| 54 | + |
| 55 | +- **15 LLMs improved** by changing only the edit tool format (hashline) |
| 56 | +- **5-68% success rate gains** across models (Grok Code Fast 1: 6.7% -> 68.3%) |
| 57 | +- **20-61% token reduction** (Grok 4 Fast output tokens dropped 61%) |
| 58 | +- **Zero training compute** required |
| 59 | + |
| 60 | +The key insight: the harness (tool layer between model output and workspace) is where most failures happen. Streaming hooks enable a new class of harness optimizations: |
| 61 | + |
| 62 | +1. **TTSR (Time-To-Stream Rules)**: Observe tokens as they stream, detect patterns (e.g., model about to repeat a known mistake), inject corrective steering before the model commits to a bad path |
| 63 | +2. **Early abort on waste**: Detect when the model is generating obviously wrong output (wrong language, hallucinated imports, infinite loops) and abort early to save tokens |
| 64 | +3. **Real-time observability**: Token-level metrics, latency tracking, pattern detection |
| 65 | + |
| 66 | +## Proposed Hooks |
| 67 | + |
| 68 | +### 1. `stream.delta` |
| 69 | + |
| 70 | +Observe individual streaming tokens/chunks. Optionally signal abort. |
| 71 | + |
| 72 | +```typescript |
| 73 | +"stream.delta"?: ( |
| 74 | + input: { |
| 75 | + sessionID: string |
| 76 | + messageID: string |
| 77 | + partID: string |
| 78 | + type: "text" | "reasoning" | "tool-input" |
| 79 | + /** For tool-input deltas, the tool name and call ID */ |
| 80 | + tool?: { name: string; callID: string } |
| 81 | + }, |
| 82 | + output: { |
| 83 | + delta: string |
| 84 | + /** Set to true to abort the current stream */ |
| 85 | + abort?: boolean |
| 86 | + }, |
| 87 | +) => Promise<void> |
| 88 | +``` |
| 89 | + |
| 90 | +**Use cases:** |
| 91 | +- TTSR: pattern-match streaming text against rules, abort when a known-bad pattern is detected |
| 92 | +- Token counting: real-time token budget enforcement |
| 93 | +- UI: progressive rendering of tool inputs (subsumes #9737) |
| 94 | +- Observability: TTFT measurement, throughput tracking |
| 95 | + |
| 96 | +### 2. `stream.aborted` |
| 97 | + |
| 98 | +Handle stream abort (whether user-initiated, plugin-initiated, or error-induced). Optionally retry or inject a steering message. |
| 99 | + |
| 100 | +```typescript |
| 101 | +"stream.aborted"?: ( |
| 102 | + input: { |
| 103 | + sessionID: string |
| 104 | + messageID: string |
| 105 | + reason: "user" | "plugin" | "error" | "timeout" |
| 106 | + /** Accumulated text so far */ |
| 107 | + partial: string |
| 108 | + /** If plugin-initiated, which plugin triggered the abort */ |
| 109 | + source?: string |
| 110 | + }, |
| 111 | + output: { |
| 112 | + /** Set to true to retry the stream from scratch */ |
| 113 | + retry?: boolean |
| 114 | + /** Inject a user message before retry (steering) */ |
| 115 | + injectMessage?: string |
| 116 | + }, |
| 117 | +) => Promise<void> |
| 118 | +``` |
| 119 | + |
| 120 | +**Use cases:** |
| 121 | +- TTSR steering: abort detected bad pattern, inject corrective instruction, retry |
| 122 | +- Graceful degradation: on timeout, inject "please be more concise" and retry |
| 123 | +- Abort analytics: track why streams are aborted, which models/prompts cause issues |
| 124 | +- Recovery: preserve partial output context for the retry attempt |
| 125 | + |
| 126 | +## Code Sketch: Changes to processor.ts |
| 127 | + |
| 128 | +The change is modest -- ~30 lines added to the existing streaming loop: |
| 129 | + |
| 130 | +```typescript |
| 131 | +// In processor.ts, within the for-await-of stream.fullStream loop: |
| 132 | + |
| 133 | +case "text-delta": |
| 134 | + if (currentText) { |
| 135 | + // NEW: trigger stream.delta hook |
| 136 | + const deltaOutput = await Plugin.trigger( |
| 137 | + "stream.delta", |
| 138 | + { |
| 139 | + sessionID: input.sessionID, |
| 140 | + messageID: input.assistantMessage.id, |
| 141 | + partID: currentText.id, |
| 142 | + type: "text", |
| 143 | + }, |
| 144 | + { delta: value.text }, |
| 145 | + ) |
| 146 | + if (deltaOutput.abort) { |
| 147 | + // Record abort reason and break out of stream |
| 148 | + abortReason = "plugin" |
| 149 | + break |
| 150 | + } |
| 151 | + |
| 152 | + currentText.text += deltaOutput.delta |
| 153 | + // ... existing updatePartDelta logic |
| 154 | + } |
| 155 | + break |
| 156 | + |
| 157 | +case "tool-input-delta": |
| 158 | + // NEW: instead of `break`, accumulate and trigger hook |
| 159 | + const toolMatch = toolcalls[value.id] |
| 160 | + if (toolMatch && toolMatch.state.status === "pending") { |
| 161 | + const deltaOutput = await Plugin.trigger( |
| 162 | + "stream.delta", |
| 163 | + { |
| 164 | + sessionID: input.sessionID, |
| 165 | + messageID: input.assistantMessage.id, |
| 166 | + partID: toolMatch.id, |
| 167 | + type: "tool-input", |
| 168 | + tool: { name: toolMatch.tool, callID: value.id }, |
| 169 | + }, |
| 170 | + { delta: value.delta }, |
| 171 | + ) |
| 172 | + if (deltaOutput.abort) { |
| 173 | + abortReason = "plugin" |
| 174 | + break |
| 175 | + } |
| 176 | + // Accumulate raw (also addresses #9737) |
| 177 | + await Session.updatePart({ |
| 178 | + ...toolMatch, |
| 179 | + state: { |
| 180 | + ...toolMatch.state, |
| 181 | + raw: (toolMatch.state.raw || "") + deltaOutput.delta, |
| 182 | + }, |
| 183 | + }) |
| 184 | + } |
| 185 | + break |
| 186 | + |
| 187 | +// After the stream loop, before error handling: |
| 188 | +if (abortReason) { |
| 189 | + const abortOutput = await Plugin.trigger( |
| 190 | + "stream.aborted", |
| 191 | + { |
| 192 | + sessionID: input.sessionID, |
| 193 | + messageID: input.assistantMessage.id, |
| 194 | + reason: abortReason, |
| 195 | + partial: currentText?.text ?? "", |
| 196 | + }, |
| 197 | + { retry: false, injectMessage: undefined }, |
| 198 | + ) |
| 199 | + if (abortOutput.retry) { |
| 200 | + if (abortOutput.injectMessage) { |
| 201 | + // Inject steering message as user input before retry |
| 202 | + await Session.addUserMessage(input.sessionID, abortOutput.injectMessage) |
| 203 | + } |
| 204 | + continue // Re-enter the while(true) loop |
| 205 | + } |
| 206 | +} |
| 207 | +``` |
| 208 | + |
| 209 | +## Design Considerations |
| 210 | + |
| 211 | +1. **Performance**: `Plugin.trigger` is already called in the hot path (`text-end`). Adding it to `text-delta` adds per-token overhead. Mitigation: only invoke if any loaded plugin registers the hook (check at plugin load time, not per-token). |
| 212 | + |
| 213 | +2. **Backward compatibility**: Plugins that don't register these hooks see zero change. The `output.abort` default is `undefined` (falsy), so existing behavior is preserved. |
| 214 | + |
| 215 | +3. **Subsumes #9737**: The `tool-input-delta` handling naturally accumulates `state.raw`, which is exactly what #9737 requests. |
| 216 | + |
| 217 | +4. **Complements #12472**: Claude Code's `PreToolUse`/`PostToolUse` map to `tool.execute.before/after`. These new hooks cover the streaming phase that Claude Code doesn't expose at all -- making OpenCode's plugin system strictly more capable. |
| 218 | + |
| 219 | +5. **Complements #13524**: The centralized hook dispatch from #13524 would naturally include these new hooks. |
0 commit comments