OpenCode Reference
t3code Compatibility
Section titled “t3code Compatibility”t3code is a desktop application that provides a unified web interface for multiple AI coding agents, including OpenCode. When OpenCode runs through t3code, some maestria agent-level controls behave differently.
How t3code drives OpenCode
Section titled “How t3code drives OpenCode”t3code spawns opencode serve and communicates through the @opencode-ai/sdk/v2 HTTP API. It replaces OpenCode’s normal configuration with OPENCODE_CONFIG_CONTENT="{}" and injects its own permission rules at session creation time (source: opencodeRuntime.ts).
Permission architecture
Section titled “Permission architecture”OpenCode’s V2 protocol uses an agent-native permission model: tool access is controlled by each agent’s permission frontmatter field and resolved at tool-use time (source: session create protocol, permission.ts). There is no session-level permission override in V2. t3code sends a permission parameter in its session.create() call, but it is a legacy V1 artifact that the V2 server ignores; agent-level permissions still apply for tool authorization.
What works under t3code
Section titled “What works under t3code”- The plugin loads and registers all 8 agents (orchestrator + 7 specialists)
- The orchestrator is selectable in t3code’s agent dropdown
- Agent prompts and system instructions load correctly
- Task delegation between agents works
- Agent-level tool permissions from frontmatter are honored by native OpenCode sessions; the full-access mode can bypass them (see Known limitations)
What changes under t3code
Section titled “What changes under t3code”| Aspect | Native OpenCode | Under t3code |
|---|---|---|
| Config loading | opencode.jsonc is loaded normally |
Overridden by OPENCODE_CONFIG_CONTENT="{}" - file-based config is ignored |
| Permission model | Agent-level permissions are authoritative | t3code injects session-level rules via SDK |
| Permission UI | OpenCode’s native prompt for approval requests | t3code intercepts permission.asked events and shows its own UI |
| Runtime mode | Agent permissions govern tool access | t3code’s runtimeMode setting (full-access / approval-required) affects the approval layer |
| Full-access mode | Respects agent-level deny rules |
Flattens to blanket allow-all at t3code’s level - agent denials may not surface correctly |
| Permission flow | Permission check -> agent config -> allow/deny/ask -> native UI | Permission check -> agent config -> allow/deny/ask -> t3code intercepts -> t3code UI -> mapped back to OpenCode |
Known limitations
Section titled “Known limitations”Approval-required mode renders the orchestrator unusable. Every tool call needs approval through t3code’s UI, even tools that maestria permits freely (like question or task), so delegation steps stall on manual clicks.
Full-access mode bypasses agent-level restrictions. The builder agent gets unrestricted bash access, and reviewer agents lose their read-only enforcement.
File-based configuration is ignored. Custom settings in opencode.jsonc (tools, model preferences, agent overrides) are not loaded under t3code.
Root cause
Section titled “Root cause”t3code was designed around OpenCode’s V1 session-level permission model. Its buildOpenCodePermissionRules() constructs a PermissionRuleset that OpenCodeAdapter.ts passes to session.create() (source), but the V2 endpoint accepts only { id, agent, model, location } with no permission field. The mismatch is architectural, not a bug in either project.
Project Loading
Section titled “Project Loading”.maestria/workflow.md then .maestria/rules.md load from the project root (SDK project worktree, then instance worktree, then session directory), read fresh on every model call, so edits need no restart. Missing or empty files are skipped; a present-but-unusable file propagates as a failed model call instead of running on overridden configuration. See Workflow Patterns for order, precedence, and carry-over.