Retinue v0.2.0

Retinue v0.2.0

Retinue v0.2.0 is the first release candidate after the OpenCode-native hardening cycle. It keeps OpenCode as the default product backend, removes Retinue-specific read-only access-mode overlays from normal OpenCode children, and makes permission and stall handling explicit enough for regular MCP use.

Chinese release notes are available at v0.2.0_RELEASE_NOTES.zh-CN.md.

What Changed Since v0.1.0

• OpenCode calls prefer the official @opencode-ai/sdk; the legacy HTTP client remains as a compatibility fallback.
• Retinue now exposes backend-neutral permission tools:
  • retinue_list_permissions
  • retinue_reply_permission
• OpenCode external_directory permission requests are surfaced to the caller with structured approval guidance instead of being hidden inside a stalled job.
• Claude Code can run through the Claude Agent SDK path, including SDK permission hooks. Retinue does not select a Claude model by default; Claude Code owns profile, endpoint, and model routing unless RETINUE_CLAUDE_MODEL is explicitly set.
• OpenCode provider and tool-call failures are classified as bounded stalled diagnostics. Recoverable failures can start one fresh task-level attempt; the failed original chain remains non-evidence.
• Retinue log audit can reconcile stale stalled traces against live backend/job state, suppress completed jobs, deduplicate recovery chains, report concise issue candidates, and separate permission attention items from backend failures.
• Daemon job-control routes now require the Retinue discovery/client token, and job id handling rejects path traversal before touching job artifacts.
• Killed OpenCode jobs remain terminal unless a real completion arrives, and no-output OpenCode roots are reported as provider_zero_progress stalled diagnostics instead of occupying active slots indefinitely.
• The packaged config is treated as a fallback default. Persistent deployment overrides should use environment variables such as RETINUE_MAX_CONCURRENT_AGENTS, RETINUE_OPENCODE_AGENT, and RETINUE_OPENCODE_ROOT_BINDING_MODE.
• Kilo and backend-candidate probes were added as evaluation paths. They are not the default product backend in v0.2.0.

Product Boundary

Retinue remains a local subagent execution surface. It is not a provider router and does not own model selection.

• Default backend: OpenCode.
• Default OpenCode agent: explore.
• Default active-child slots from packaged config: 3; the default shared machine-level budget is max(5, RETINUE_MAX_CONCURRENT_AGENTS). Deployments can override the per-session limit with RETINUE_MAX_CONCURRENT_AGENTS and the shared machine-level budget with RETINUE_GLOBAL_AGENT_BUDGET.
• Overflow now defaults to RETINUE_OVERFLOW_STRATEGY=queue: full session/global active slots return queued job handles and promote them when slots open. RETINUE_OVERFLOW_STRATEGY=evict preserves the old same-session oldest-running eviction behavior. RETINUE_MAX_QUEUED_AGENTS defaults to 20; queue exhaustion returns resource_exhausted with reason: "queue_full".
• Default OpenCode root binding mode remains per-spawn. shared-root is available behind RETINUE_OPENCODE_ROOT_BINDING_MODE=shared_root for deployment experiments.
• Backend, profile, model, OpenCode server, access mode, and bash policy are not normal per-tool arguments.

Reliability and Operations

• Permission requests are now first-class MCP workflow events instead of opaque stalls, and permission wait responses keep raw stderr compact so the required supervisor action stays visible.
• Provider and tool-call failures are bounded as stalled diagnostics rather than trusted results.
• Log audit support is available for maintainers, but diagnostic tooling stays outside the default product tool surface.
• Release validation is tracked through the repository gate and maintainer runbooks rather than embedded in public release notes.

Upgrade Notes

• Compared with the v0.1.0 tag, the packaged default OpenCode agent changed from plan to explore. Deployments that depended on plan behavior should set RETINUE_OPENCODE_AGENT=plan explicitly.
• If you edited the packaged retinue.config.json, move persistent settings to environment variables. Plugin refreshes may overwrite packaged config files.
• If you need more concurrent children, set RETINUE_MAX_CONCURRENT_AGENTS in the Codex host or MCP server environment.
• If your MCP host has a shorter tool timeout than Retinue's 180-second wait cap, set RETINUE_MCP_WAIT_MAX_MS to match that host limit.
• If you opt into shared OpenCode roots, keep logs separated by externalRunnerMode, externalRootSessionId, and child externalSessionId.

Retinue v0.1.0

Retinue v0.1.0

Retinue v0.1.0 is the first release that is ready for day-to-day use: after installing the Codex plugin, Codex can use OpenCode as a local child agent and complete the basic spawn, wait, list, and close workflow.

Chinese release notes are available at v0.1.0_RELEASE_NOTES.zh-CN.md.

What This Release Provides

• Plugin marketplace installation for Codex; users do not need to clone the repository or build from source.
• OpenCode is the default backend, using the OpenCode plan agent by default.
• Retinue manages the local OpenCode server lifecycle by default.
• When 4096 is occupied by an external service, Retinue tries fallback ports from 4097 through 4127.
• Product MCP tools:
  • retinue_spawn_agent
  • retinue_wait_agent
  • retinue_close_agent
  • retinue_list_agents
• Per-MCP-session child-agent slots. When the slot limit is exceeded, Retinue closes the oldest still-running child agent to make room for the new task.
• retinue_wait_agent returns the child result when the task is terminal. While the task is still running, it returns a compact diagnostic summary, job paths, and bounded stdout/stderr tails so the caller can decide whether to wait, inspect logs, or close the task. OpenCode empty-output, stale incomplete assistant rounds, and read-only patch/write intent are reported as stalled diagnostics instead of being treated as successful results, and stalled jobs no longer occupy the active MCP session slot. Default read-only OpenCode runs also disable nested task delegation and use non-interactive session permissions with a read-only shell inspection allowlist, so review jobs can inspect repositories without recursively spawning internal OpenCode subagents or waiting for headless approval prompts.
• Package smoke checks now start the bundled MCP runtime from both the root build output and the plugin-local bootstrap.

Install

Add the Retinue plugin marketplace:

codex plugin marketplace add Disaster-Terminator/Retinue

Then open Codex, run /plugins, select [Retinue Local], open the Retinue details page, choose Install plugin, and restart Codex.

After restart, ask Codex:

Use Retinue to spawn an OpenCode plan subagent. Ask it to reply exactly: RETINUE_OK. Wait for the result and close the child agent.

Requirements

• Node.js 20+
• Codex CLI with plugin support
• OpenCode 1.14+, preferably installed with the official script:

curl -fsSL https://opencode.ai/install | bash

Managed OpenCode auto-serve binds to loopback by default. Set RETINUE_OPENCODE_ALLOW_NON_LOOPBACK=1 only for explicitly isolated environments that intentionally expose the OpenCode server host.

Boundaries

• OpenCode continues to own provider, model, login state, quota, and profile configuration.
• Retinue does not expose backend/profile/model/agent/OpenCode server choices as per-call tool arguments. It exposes only access_mode so callers can keep child agents read-only by default or explicitly follow the active OpenCode profile for one spawn.
• Claude Code support remains available for custom deployments, but OpenCode is the default v0.1.0 product path.