Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md

Large diffs are not rendered by default.

17 changes: 3 additions & 14 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,20 +182,6 @@ them ran in this directory.
Questions the maintainer still owes an answer on. Written here the turn they are
raised, so they survive context compaction; removed when answered, done or dropped.

- 2026-11-14: watchdog follow-up: should the plugin wait longer after an API error than Claude Code
announces? Maintainer 2026-11-15: "maybe yes how much longer is needed is this something usefull for
all plugin users?" Measured 2026-11-15: opencode.db holds 51 real `▌ **stream timeout:**` closes
since 2026-09 (22 Sep, 19 Oct, 10 Nov, about four a week). 11 had a Claude Code `api_error` in the
same directory during the step, and 7 of those closed 0 to 2 s after it: Claude Code gave up on a
stalled connection (`Connection error.`, 288 of the 292 api_error records in both config dirs'
transcripts) at about the moment the 60 s inactivity watchdog fired, so the turn was closed just
before the retry was announced (v0.73.4 holds the watchdog only for a retry announced first). Claude
Code's own backoff: median 1 s, p90 10 s, max 40 s. Silence in the transcript before a Connection
error clusters at about 30 s (median 30.0 s) and at 300 s or more (29); Claude Code's own stall
timeout was not read off the binary (the shell redacted it). Recommendation: lengthen the inactivity
window from 60 s to 90 s by default for everyone (`CLAUDE_CODE_RESULT_FALLBACK_MS` stays the
override); cost: a truly hung CLI is noticed 30 s later. The other 40 closes have no retry behind
them (the sleep case is fixed in v0.73.4); their cause is not diagnosed.
- 2026-11-10: what to build next from Future Features (doctor warnings for setups that fail silently,
model aliases such as `opus`, a `task_send` to steer a background subagent, continuing a terminal
`claude` session in opencode): pick any, or hold.
Expand Down Expand Up @@ -254,6 +240,9 @@ Verification still owed, copied from the vault's `Future Features.md` "Next up"

## Done

- 2026-11-15: **done** (h #g318): the wire-inactivity watchdog defaults to 90 s instead of 60, because 7
of 51 `stream timeout` closes on this machine came 0 to 2 s before Claude Code announced a retry after
a stalled connection. Still open: the other 40 closes had no retry behind them and are not diagnosed.
- 2026-11-15: **done**, by the maintainer's own config: `AGENT_GUARD_PROMPT_GUARD_MODE=warn` set
globally, so agent-guard warns instead of blocking a prompt with secret-like values. The stuck
session `ses_e324dbf7bffeRHQIz10AIxm7dT` recovered: its 03:28:31Z replay (208,149 characters, the
Expand Down
31 changes: 31 additions & 0 deletions docs/agents-history.md
Original file line number Diff line number Diff line change
Expand Up @@ -13186,3 +13186,34 @@ Shipped as v0.73.5 on 2026-11-15 (PR #189), a patch: CI green on Linux and Windo
`569ae0e`, on the merge commit `51bc536` before the tag and on the release commit `879d36b`, the
publish confirmed by the `Publish package` step's tail and the version document's shasum
(`0f49e6ca`), with a GitHub Release.


## The inactivity watchdog closed turns just before Claude Code announced a retry (2026-11-15)

h #g318. The follow-up to h #g316, which made both watchdogs wait out a backoff the CLI announces
(`noteAnnouncedRetry`) but only when the `system`/`api_retry` frame arrives before the window runs out.
The maintainer asked whether the plugin should wait longer than Claude Code announces, and whether
that helps every user.

Measured on this machine on 2026-11-15, read-only:

- opencode.db: 51 assistant messages carry a text part that starts with `▌ **stream timeout:**`
(22 in September, 19 in October, 10 in November), about four a week. A plain `LIKE` found 108, the
rest being messages that quote the note.
- Both config dirs' Claude Code transcripts hold 292 `system`/`api_error` records: 288
`Connection error.`, 3 expired OAuth tokens, 1 `Request timed out.` Claude Code's announced backoff
(`retryInMs`): median 1,003 ms, p90 9,887 ms, max 39,611 ms.
- 11 of the 51 closes had an `api_error` in the same directory during the step, and 7 of those came
0 to 2 s after it: the CLI gave up on a stalled connection at about the moment the 60 s window ran
out, and the turn was closed before the retry could hold it. The other 4 closed 27 to 153 s after
their retry, so a retry was not their cause.
- The transcript silence before a `Connection error.` clusters at about 30 s (median 30.0 s, p75
30.6 s) and at 300 s or more (29 of 217). Claude Code's own stall timeout was not read off the
binary (the shell output redacted the surrounding code), so the tie is inferred from timing.

Change: `resolveResultFallbackMs` defaults to 90,000 ms. That clears the tie with 30 s of margin over
the longest observed timing and over Claude Code's p90 backoff; the cost is that a CLI that is alive
but wedged is closed 30 s later. A network stall is not specific to this machine, so the default
changes for every user. `CLAUDE_CODE_RESULT_FALLBACK_MS` stays the override and the test seam, so
there is no option. The other 40 closes had no retry behind them and are not diagnosed (the sleep
case among them is h #g316). `test/result-fallback.test.ts` pins the default and the override.
2 changes: 1 addition & 1 deletion docs/configuration/environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Every variable the plugin itself reads, in one place. Config is read once at ope
| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | Claude Code itself | Set to `0` for the interactive TUI unless you set it, so a long proxied call is not moved to the background after 120 s (headless sessions never do this). |
| `CLAUDE_CODE_START_WATCHDOG_MS` | start watchdog | Milliseconds a `claude` process may stay completely silent on stdout after a turn is written, or after a proxy tool result should have resumed it, before the plugin acts. First expiry respawns the process and resumes the session; a second ends the turn with an error rather than hanging. Default `90000`; a positive integer is required and anything else falls back to that. A process that has not yet sent its first `system`/`init` line gets at least its `MCP_TIMEOUT` plus 30 s instead (150 s by default), because Claude Code sends that line only once its MCP servers have connected or timed out; from that line on, this value applies. Mainly a knob for reproducing the hang. |
| `CLAUDE_CODE_LIVE_SWITCH_TIMEOUT_MS` | live model switch | Milliseconds one `set_model` or `apply_flag_settings` control request may take before a live model or effort change (`liveModelSwitch`) gives up, stops the process and falls back to starting a new one with `--resume`. Default `10000`; a positive integer is required and anything else falls back to that. Claude Code answered in 0.5 to 0.7 s for a model and well under a second for an effort when measured. |
| `CLAUDE_CODE_RESULT_FALLBACK_MS` | wire-inactivity watchdog | Milliseconds a `claude` process that has already produced output may stay silent on stdout before the turn is closed without a `result`. The close is announced in the reply as a `▌ **stream timeout:**` note. Default `60000`; a positive integer is required and anything else falls back to that. Like the start watchdog, mainly a knob for reproducing a hang. |
| `CLAUDE_CODE_RESULT_FALLBACK_MS` | wire-inactivity watchdog | Milliseconds a `claude` process that has already produced output may stay silent on stdout before the turn is closed without a `result`. The close is announced in the reply as a `▌ **stream timeout:**` note. Default `90000` (60000 before v0.73.6, which closed some turns just before Claude Code announced a retry after a stalled connection); a positive integer is required and anything else falls back to that. Like the start watchdog, mainly a knob for reproducing a hang. |
| `OPENCODE_CLAUDE_CODE_LOG_FILE` | logger | `1` writes the log file, `0` forces it off even when `logging.file` is `true`. See [Logging](../configuration/logging.md). |
| `OPENCODE_CLAUDE_CODE_LOG_DIR` | logger | Directory for the log file, overriding `logging.dir`. |
| `OPENCODE_CLAUDE_CODE_MODEL_PROBE` | model catalog | `0` or `false` stops the background model probe for this environment (the test suite sets it). An answer already stored is still registered; `cliModelCatalog: false` is the config switch that ignores it too. |
Expand Down
2 changes: 1 addition & 1 deletion docs/guides/tool-proxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,7 +224,7 @@ A deadline does not count time opencode is still spending on the call. When it p

`question` keeps 30 minutes because it blocks on a human reading a form, and a form nobody answers is not an event. A positive `task` override restores a wall-clock backstop for operators who want one; if it fires, the error tells Claude not to "schedule a wake-up": that is a Claude Code affordance which cannot fire in this headless/proxy context, so deferring silently loses the work.

Two watchdogs are a different thing again and are unchanged: the start watchdog (90 s of complete silence after a turn is written, 150 s for a new process still waiting on its MCP servers, respawn then error, see `CLAUDE_CODE_START_WATCHDOG_MS`) and the wire-inactivity watchdog (60 s of silence after content, see `CLAUDE_CODE_RESULT_FALLBACK_MS`; when it fires the reply gets a `▌ **stream timeout:**` note so the turn does not just stop, and the CLI's turn is interrupted so it does not run on with nobody listening; a fire that comes well past its deadline because the machine slept waits a fresh 60 s instead). Those exist because a process that is alive but wedged emits no event to listen to, and a proxy call is never what they are waiting on: a CLI parked inside a proxied tool is producing nothing on purpose, and both watchdogs know that.
Two watchdogs are a different thing again and are unchanged: the start watchdog (90 s of complete silence after a turn is written, 150 s for a new process still waiting on its MCP servers, respawn then error, see `CLAUDE_CODE_START_WATCHDOG_MS`) and the wire-inactivity watchdog (90 s of silence after content, see `CLAUDE_CODE_RESULT_FALLBACK_MS`; when it fires the reply gets a `▌ **stream timeout:**` note so the turn does not just stop, and the CLI's turn is interrupted so it does not run on with nobody listening; a fire that comes well past its deadline because the machine slept waits a fresh 90 s instead). Those exist because a process that is alive but wedged emits no event to listen to, and a proxy call is never what they are waiting on: a CLI parked inside a proxied tool is producing nothing on purpose, and both watchdogs know that.

If Claude nevertheless abandons the HTTP call, the plugin preserves narration emitted while opencode was running the tool, renders it on return, and delivers the late completion as a plain-text continuation naming the original call. It tells Claude not to run the tool again. A silent post-tool continuation gets one resumed-process retry, preserving the original model, account, effort, and proxy configuration; a second failure ends with an error rather than an indefinite hang. Buffered narration is capped at 500 lines and 2 MiB, with a warning if output was dropped.

Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting/known-limitations.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ sidebar:
- **Empty text blocks are dropped.** Claude sometimes opens a `content_block_start` for text but never sends a delta. The plugin no longer emits the empty block (which was triggering Anthropic 400s like `cache_control cannot be set for empty text blocks`).
- **Smart incomplete-turn continuation.** By default, the plugin keeps the current opencode stream open and feeds Claude CLI a small internal continuation message when Claude emits a `result` after reasoning/tool activity without a useful visible answer. It still stops normally on final-looking answers, questions, blockers, errors, aborts, or internal safety-budget exhaustion. It also resumes an answer the model was cut off mid-sentence: a `max_tokens` stop means truncation rather than completion, so the turn continues instead of ending on half a sentence, capped at 8 attempts and 10 minutes. Every other stop reason is taken at face value. Disable with `"autoContinueIncompleteTurns": false`.
- **`AskUserQuestion`** from the CLI is converted into plain text content rather than forwarded as a tool call, unless `"Question"` is in `proxyTools`, in which case it is routed through opencode's native `question` tool (see [AskUserQuestion](../configuration/permissions.md#askuserquestion)).
- **Wire-inactivity watchdog.** Once the CLI has produced any content, the stream closes gracefully if stdout goes silent for 60 seconds without a `result` message arriving. Resets on every line received, so long mid-turn pauses (Sonnet between text-end and the next tool_use, for example) are tolerated. On a user-initiated abort, the watchdog shortens to 5 seconds.
- **Wire-inactivity watchdog.** Once the CLI has produced any content, the stream closes gracefully if stdout goes silent for 90 seconds without a `result` message arriving. Resets on every line received, so long mid-turn pauses (Sonnet between text-end and the next tool_use, for example) are tolerated. On a user-initiated abort, the watchdog shortens to 5 seconds.
- **Context usage, not turn totals.** The CLI's `result` adds up every API call in a turn, and opencode reads a message's usage as how full the context is, so a tool-heavy turn looked several times its real size and triggered auto-compaction far below the window. The plugin reports the last API call's input and cache counts plus the turn's output instead. See [Per-turn stats](../guides/turn-stats.md) for what that does to opencode's cost figure.
- **Lazy `cwd`.** The working directory is re-resolved at every request, so opencode's project-aware behavior works without restarting the plugin.
- **Instruction files are sent once.** Claude Code 2.1.277 and later read a project's `AGENTS.md` themselves, and always read `CLAUDE.md`, while opencode sends its `AGENTS.md` in the system prompt, so the same file used to reach Claude twice (about 3,000 tokens for a 9 KB file, measured on Claude Code 2.1.322, on every new conversation and kept for its whole length). The plugin now tells Claude Code to skip its own copy of any `AGENTS.md` or `CLAUDE.md` whose whole text the system prompt already holds, including a `CLAUDE.md` that is a copy or a symlink of `AGENTS.md`. It never skips a file that imports another file, and when a conversation resumes it only skips a file whose current text the conversation already has, so an edit still reaches Claude. Your own `claudeMdExcludes` in Claude Code's settings still apply. Default transport only, not on Windows.
Expand Down
2 changes: 1 addition & 1 deletion skills/claude-code-plugin/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ their secret values. Arbitrary MCP `{env:NAME}` placeholders are outside this li
| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | Set to `0` for the interactive TUI unless the operator set it, so a proxied call past 120 s stays in the foreground as on headless. `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` is not set: it covers MCP-task servers only, which the proxy never is, and at `0` the CLI asks no server for a task. |
| `CLAUDE_CODE_START_WATCHDOG_MS` | Positive integer ms before a headless start or proxy-result continuation is considered silent; default 90000 for missing/invalid/nonpositive values. First expiry respawns, second errors. Bookkeeping-only output is not progress. A process that has not sent its first `system`/`init` yet gets at least its `MCP_TIMEOUT` plus 30 s (150 s by default), since the CLI sends `init` only after its MCP servers connect or time out; the log's `beforeInit` says which delay fired. Keep within timer range; do not lower for routine config checks. |
| `CLAUDE_CODE_LIVE_SWITCH_TIMEOUT_MS` | Positive integer ms one `set_model` or `apply_flag_settings` may take before a live model or effort switch gives up, stops the child and falls back to the respawn; default 10000 for missing/invalid/nonpositive values. Measured answers: 0.5 to 0.7 s and 20 to 140 ms. |
| `CLAUDE_CODE_RESULT_FALLBACK_MS` | Positive integer ms of stdout silence, after the CLI has produced output, before the turn is closed with no `result`; default 60000 for missing/invalid/nonpositive values. The close is announced in the reply as a `▌ **stream timeout:**` note, which is stripped from any rebuilt transcript, and interrupts the CLI's turn so it does not run on unattended. An aborted turn gets no note. A fire more than 5 s past its deadline (the machine slept, or the event loop stalled) waits a fresh full delay instead, because that silence was never observed, and an `api_retry` frame adds the `retry_delay_ms` the CLI announces (h #g316). The start watchdog (`CLAUDE_CODE_START_WATCHDOG_MS`) follows the same two rules. |
| `CLAUDE_CODE_RESULT_FALLBACK_MS` | Positive integer ms of stdout silence, after the CLI has produced output, before the turn is closed with no `result`; default 90000 for missing/invalid/nonpositive values (60000 before v0.73.6: Claude Code announces a retry after a stalled API connection at about 60 s, and the watchdog closed some of those turns first). The close is announced in the reply as a `▌ **stream timeout:**` note, which is stripped from any rebuilt transcript, and interrupts the CLI's turn so it does not run on unattended. An aborted turn gets no note. A fire more than 5 s past its deadline (the machine slept, or the event loop stalled) waits a fresh full delay instead, because that silence was never observed, and an `api_retry` frame adds the `retry_delay_ms` the CLI announces (h #g316). The start watchdog (`CLAUDE_CODE_START_WATCHDOG_MS`) follows the same two rules. |
| `OPENCODE_CLAUDE_CODE_LOG_FILE` | Overrides `logging.file`: trimmed `0/false/no/off` are false; any other nonempty value is true; empty falls back to config. Prefer `1` or `0`. |
| `OPENCODE_CLAUDE_CODE_LOG_DIR` | Overrides `logging.dir`. |
| `OPENCODE_CLAUDE_CODE_MODEL_PROBE` | `0` or `false` stops the background model probe for this environment (the `npm test` script sets it); the stored answer is still registered. `cliModelCatalog: false` is the config switch and also ignores the stored answer. |
Expand Down
2 changes: 1 addition & 1 deletion src/claude-session-bun.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1126,7 +1126,7 @@ export class ClaudeSession {
submitMaxRetries: opts.submitMaxRetries ?? 8,
debug: opts.debug ?? false,
// The headless CLI's `tool_progress` heartbeat runs every 30 s, and the
// wire-inactivity watchdog it keeps quiet fires at 60 s.
// wire-inactivity watchdog it keeps quiet fires at 90 s.
heartbeatMs: opts.heartbeatMs ?? 30_000,
interruptGraceMs: opts.interruptGraceMs ?? 5_000,
// Shorter than `bootQuietMs`, so a trust dialog is answered before boot
Expand Down
6 changes: 3 additions & 3 deletions src/cli-events.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1635,9 +1635,9 @@ export function _resetToolProgressReports(): void {
*
* The one job a progress frame could have done is already done for free. The
* line handler calls `startResultFallback` on every line it receives, so a
* heartbeat resets the 60-second wire-inactivity watchdog like any other line,
* and the measured 30-second cadence keeps a long CLI-executed tool at half
* the deadline. What was missing was not the reset but the diagnostic: until
* heartbeat resets the 90-second wire-inactivity watchdog like any other line,
* and the measured 30-second cadence keeps a long CLI-executed tool at a third
* of the deadline. What was missing was not the reset but the diagnostic: until
* now a turn stuck inside a ten-minute `Bash` wrote twenty `stream message
* tool_progress` debug lines that named neither the tool nor how long it had
* been going. That is what the INFO line below says.
Expand Down
8 changes: 6 additions & 2 deletions src/turn-state.ts
Original file line number Diff line number Diff line change
Expand Up @@ -397,11 +397,15 @@ export interface TurnStateInit {
/**
* Wire-inactivity watchdog delay. Read per turn, because the regression test
* sets the env var between runs.
*
* 90 s, not 60 (h #g318): Claude Code gives up on a stalled API connection and
* announces its retry at about the 60 s mark, and on this machine 7 turns were
* closed 0 to 2 s before that announcement could hold the watchdog.
*/
function resolveResultFallbackMs(): number {
export function resolveResultFallbackMs(): number {
const env = process.env.CLAUDE_CODE_RESULT_FALLBACK_MS
const parsed = env ? Number.parseInt(env, 10) : NaN
return Number.isFinite(parsed) && parsed > 0 ? parsed : 60_000
return Number.isFinite(parsed) && parsed > 0 ? parsed : 90_000
}

/** Start watchdog delay, read per turn for the same reason. */
Expand Down
Loading
Loading