[FEATURE]: add session.stopping plugin hook to allow re-entering the agent loop

[yehudacohen]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Plugins have no way to prevent the agent loop from stopping. When the loop is about to break, there is no hook that fires — so a plugin cannot inspect session state and inject a follow-up message to keep the agent working.

Why session.idle is not sufficient:

session.idle fires after the loop has already broken. A plugin receiving it can call client.session.chat to re-prompt, but this has two problems:

1. In opencode run mode, process teardown races against the re-prompt (opencode run teardown race after session.idle can create empty continuation assistant turn ("parts": []) #15267). The continuation turn can arrive after disposal has begun.
2. The injected message appears as a visible user message in the conversation. For use cases like workflow phase gates — where the intent is a silent "you're not done yet, keep working" — this is the wrong UX.

A hook that fires before the break avoids both problems. The re-entry happens inside the existing loop iteration with no new HTTP call, no disposal race, and the injected message uses the same internal path as a normal user turn.

Proposed solution: add a session.stopping hook to the plugin Hooks interface. A plugin sets output.stop = false and provides output.message to inject a user message and continue the loop. If no plugin modifies the output, behaviour is unchanged.

Known limitation: if a plugin unconditionally returns stop=false, the loop will run forever. Plugins are responsible for their own termination condition (e.g. a marker file, a state flag, a counter). This is consistent with how other re-entry patterns work in the plugin API.

Example use case: a workflow plugin that gates on phase completion. If the agent decides it is done but the workflow state machine says an active phase is incomplete, the plugin injects a silent continuation message. This is the same mechanism Claude Code's Stop hooks use (#12472) — if a Stop hook exits with code 2, its stderr is injected as a prompt and the agent resumes.

[github-actions]

Thanks for updating the issue! It now follows the contributing guidelines and the needs:compliance label has been removed.

[Eitan1112]

+1, hitting exactly this. We use OpenCode as a headless coding agent in sandboxes. Our auto-sync plugin commits + pushes on session.idle, then polls GitLab CI to check if DB migrations passed. Problem is session.idle fires after the agent already responded, so the CI result arrives as a delayed follow-up — the user sees "done!" and then a second message about migration status.

We dug into the code and the root cause is straightforward: hook["event"]?.() in plugin/index.ts L138 isn't awaited. The type signature already says Promise<void> but the promise is dropped.

One minimal approach that wouldn't break existing plugins: add an event.sync hook alongside event. Same signature, but awaited. Plugins that need blocking behavior opt into it, everyone else stays on fire-and-forget event.

// plugin/index.ts init()
Bus.subscribeAll(async (input) => {
  const hooks = await state().then((x) => x.hooks)
  for (const hook of hooks) {
    hook["event"]?.({ event: input })          // existing — fire-and-forget
    await hook["event.sync"]?.({ event: input }) // new — awaited
  }
})

Happy to put up a PR if the team is open to this direction.