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.