npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

opencode-task-complete

v0.1.1

Published

OpenCode V2 plugin: the task_complete tool - the model's explicit 'I am finished' signal, with the v1 todo gate and ack self-loop guard, observable by any plugin.

Readme

opencode-task-complete

The task_complete tool for OpenCode v2 — the model's explicit "I am finished" signal, and the thing that makes a watcher (auto-resume) stand down instead of nudging a finished session back to life.

v2 removed v1's task_complete. This plugin puts it back, as a general capability rather than a private copy inside one watcher: the tool registry is one global map per opencode server, so every plugin can list it, extend it and observe its calls.

# opencode.jsonc
"plugins": [
  "opencode-task-complete@latest"
]

or, from a checkout:

{ "package": "file:///path/to/opencode-task-complete" }

In the box: the plugin (index.js), a test suite (test/), a worked consumer example (examples/watcher/), a changelog and contributing notes. No runtime dependencies.

Check it works in one turn — with the plugin installed, ask for a no-op task and look for the model calling task_complete and ending its reply with TASK COMPLETE on its own last line:

> This is a no-op task: there is nothing to do here. Finish your turn now.

The tool

| | | |---|---| | name | task_complete | | arguments | none — the signal is the call, not a payload | | surface | direct: the model calls it itself (see below) | | result | { content, metadata: { completed: true } } — or metadata: { completed: false, openTodos: N } when the todo gate refused it |

Why it is a DIRECT tool

The tool registers with options: { codemode: false }. Without that option a plugin tool lands in the Code Mode catalog and is only reachable through the execute runtime — the model can never call it, and any instruction to do so ends in an unknown-tool error. In opencode's core (packages/core/src/tool.ts) the registry is split in two: direct — the tools with codemode === false — and the Code Mode catalog, and only direct reaches the model as a top-level tool. The opencode-todolist plugin (npm [email protected]) uses the same switch.

v1 semantics, kept

  • The todo gate. A completion is refused while todos are still open, and the result names them. A model that keeps calling after that is a loop, not a worker, so the block is bounded (maxOverrides, default 3): after that the call is believed.

    The gate reads the todowrite history, so it needs no todo plugin: with none installed there is no list, the gate never refuses, and the tool is a pure completion signal. The model then tracks its work wherever the operator's protocol says — a findings file or a todo file — and the completion signal is the same either way.

  • The ack self-loop guard. The ack is fed straight back into the turn, and a stuck model answers it by calling the tool again rather than ending with text (v1 logged 27 consecutive acked calls with zero new user input). So the first call acks with an explicit stop instruction, the second warns, the third throws to force the turn to end.

  • The counter resets on a new inbound user message and on any other tool call, so the escalation measures a genuinely stuck loop and not several legitimate rounds of work.

The two completion signals

There are two ways a model can say "I am finished", and a watcher has to understand both:

  1. The tool call. task_complete — structured, machine-readable, and the result says whether the todo gate accepted it. This is what this plugin provides.

  2. The bare line. TASK COMPLETE, alone on the last line of the reply. Any watcher can read that out of the transcript, with no tool involved at all — which is why the protocol below teaches it unconditionally, even though the tool is right there:

    • opencode withholds tools from sessions created before the last restart, so a session that predates this plugin's install cannot call it at all;
    • a tool can be disabled for a session, or the plugin may not be installed on the box at all.

    The line is the signal that always works, so the model emits it either way.

Neither signal is auto-resume-specific. Any plugin that watches sessions can use either; auto-resume is just one that does.

Subagents are not counted. A worker's completion is the controller's business: the controller is already notified when a worker finishes, and what it reads is the worker's own contract — the DONE: <one-line summary> the controller specified for that worker. So the plugin does not teach workers the protocol, and the tool's todo gate is skipped for them (v1 parity: v1 registered the tool globally, a subagent could call it, and it changed nothing for the parent).

The protocol

The plugin injects the completion rule into the session's system prompt, so the model knows when to call the tool even in an install with no AGENTS.md and no other plugin: opencode exposes a context session hook that fires before every model request, and the rule is pushed onto the request's system prompt there.

Task completion: when all the requested work is done, call the task_complete tool once - that is what stops the automatic continue nudges. If todo tools are available, mark every todo completed first: a completion with open items is refused and you are told what is left. If there are no todo tools, keep the work list in a findings file or a todo file and mark items done there instead. Call it once, then end the turn with a brief text reply. Always end that reply with the bare words TASK COMPLETE on their own last line - even when the tool was available, because opencode withholds tools from sessions created before the last restart, and the line is the completion signal that always works: a watcher reads it from the transcript.

It checks first. If the rule is already in effect - an operator's AGENTS.md, an agent file, another plugin's injection - the plugin stays quiet rather than saying the same thing twice on every request.

The bare-line fallback (TASK COMPLETE on its own last line) is the other half of the protocol, and it needs no plugin: a watcher can detect the end-anchored line itself.


How a plugin checks for task completion

Two ways, and the second is the one that generalises.

1. Watch the tool call (recommended)

Every plugin in the server can observe the call through the registry's execute.after hook. The event carries the tool name, the session, the status and the result — so a consumer does not need to own the tool, and does not need to poll anything:

ctx.tool.hook("execute.after", async (event) => {
  if (event.tool !== "task_complete") return
  if (event.status !== "completed") return

  const completed = event.result?.metadata?.completed !== false
  if (!completed) {
    // The todo gate refused it: event.result.metadata.openTodos says how
    // many are still open, and event.result.content names them.
    return
  }
  // The model says the work is done.
})

event.result.metadata.completed is the channel: true = the completion was accepted, false = the todo gate refused it (metadata.openTodos says how many are open). A consumer that only cares about "the work is done" checks completed === true and ignores everything else.

2. Read the tool's own state

A plugin that wants the completion state of a session it is driving can also look for the tool in the registry and call it the way a model would — the tool is a normal tool, so ctx.tool.list() and the editor APIs work on it like on any other.

3. The text fallback

With no tool in the session, the protocol's other half applies: the reply ends with the bare words TASK COMPLETE on their own last line, and a watcher detects that end-anchored line itself. A watcher that supports both is covered whichever way the model signals.


Example: auto-resume

auto-resume (the stall watchdog) is the worked example. It exists to wake a session that stopped mid-flight — but a session that has finished must not be woken, so it needs to know when the model says it is done. It does not own the tool; it observes it:

// auto-resume: src/v2/index.ts
ctx.tool.hook("execute.after", async (event: any) => {
    if (event?.tool !== "task_complete") return
    if (event?.status !== "completed") return
    const sid = event?.sessionID
    if (!sid) return
    const w = ensureWatch(sid)
    const result = event?.result
    if (result?.metadata?.completed === false) {
        // The todo gate refused it: name the work that is left. The tool
        // result carries the reminder, but a collapsed tool result would hide
        // it, so auto-resume injects it too.
        const content = typeof result?.content === "string" ? result.content : ""
        if (content) await injectOnce(sid, content, "task-complete-blocked")
        return
    }
    // The stand-down: the completion latch stops the nudges.
    w.completionSignaled = true
    w.completionSignaledAt = Date.now()
})

auto-resume also keeps a fallback copy of the tool, registered only when nothing else provides it, so it still works as-is in an install without this plugin. It decides by two signals: the live tool list (does a task_complete tool already exist in the registry?), and — decisively, because plugins load in the order they are listed in the config, so a plugin listed after auto-resume has not registered its tool yet — the config file (does opencode.jsonc list a task-complete plugin at all?).


Where the todo list comes from

When the opencode-todolist plugin (npm [email protected]) IS installed, the list belongs to it, and plugin storage is namespaced per plugin id, so the list is read the way that plugin's own TUI reads it: the newest completed todowrite tool part in the session history. A todowrite REPLACES the whole list, so the newest such call IS the current list. An entry with an unrecognized status is kept rather than dropped: only pending/in_progress count as open, so an unknown status reads as closed — and dropping it would shrink the list, which is the dangerous direction (it makes real open work look finished).

Tests

bun test test/

Repository

License

MIT — see LICENSE. The session todo-list parser is derived from the npm package [email protected] — aiev/opencode-todolist, tag v0.6.1, file src/tui-data.ts (MIT, © 2026 aiev). The third-party notice is in the LICENSE file.