RFC: Running uf in a FullSend BYOA container

[sonupreetam]

Context

FullSend's built-in code agent implements whatever work is assigned to it — it does not enforce a spec-first workflow. For teams practicing spec-driven development (via Speckit and OpenSpec), this means the discipline that exists in local development environments disappears once work moves to FullSend.

uf already solves this problem: constitution enforcement, phase boundaries, Speckit/OpenSpec routing logic, and convention packs ensure that agents do not implement without an approved spec. The challenge is bringing that into a FullSend container with full parity — the agent must behave identically whether running locally in OpenCode or inside a FullSend sandbox.

Core question: How should uf run in a FullSend BYOA container? The standard BYOA path (skills, config overrides) was designed for lightweight customizations. uf is a full methodology with orchestration, 48 commands, convention packs, and review council — a different category of use case.

Non-negotiable requirement: Spec-driven development must be enforced. The agent must refuse to implement without an approved spec.

---

How FullSend BYOA Works

A custom agent in FullSend has two parts:

1. Harness file (YAML) — how the agent runs: sandbox image, policy, scripts, skills, credentials, timeouts.
2. Agent definition (Markdown) — what the agent does: prompt, tools, model, skills.

The key mechanism for customization is base: composition — inherit a built-in agent and override or extend specific fields. Skills mount domain knowledge into the sandbox that the agent reads before acting.

Reference: Bring Your Own Agent guide

---

Approach A: FullSend as Infrastructure, OpenCode + uf as Runtime (Recommended)

Treat FullSend as the infrastructure layer (sandbox, credentials, dispatch, GitHub event routing) and run OpenCode + uf as the agent runtime inside the container. The agent is OpenCode reading the repo's .opencode/ directory — same as local development.

┌── FullSend (infrastructure) ────────────────────┐
│  Sandbox isolation, WIF credentials,            │
│  GitHub event dispatch, trigger routing         │
└─────────────────────────────────────────────────┘
        │
        ▼
┌── Container ────────────────────────────────────┐
│  OpenCode (agent runtime)                       │
│    └── reads .opencode/ from mounted repo       │
│  uf binary (orchestration CLI)                  │
│    └── speckit, openspec, scaffold, review      │
└─────────────────────────────────────────────────┘
        │
        ▼
┌── Repo (.opencode/ — already exists) ───────────┐
│  commands/    → /speckit.*, /opsx-*, /unleash   │
│  agents/      → cobalt-crush-dev, divisor-*     │
│  uf/packs/    → convention packs (MUST rules)   │
│  .specify/    → constitution, templates         │
└─────────────────────────────────────────────────┘

Why this approach:

• Parity — same .opencode/ directory, same commands, same behavior locally and in FullSend. No "FullSend-lite" version to maintain.
• Slash commands work natively — OpenCode reads .opencode/commands/ and executes them directly. No translation to FullSend skills needed.
• Convention packs enforced — OpenCode reads .opencode/uf/packs/ automatically.
• Constitution gates active — phase boundaries, spec-first mandate, review council — all present.
• FullSend does what it's good at — sandbox isolation, credential delivery (WIF), event-driven dispatch. It doesn't need to be the agent brain.

What the BYOA harness provides:

# harness/uf-code.yaml
image: ghcr.io/unbound-force/uf-sandbox:latest   # Custom image with OpenCode + uf
policy: policies/base.yaml
role: uf-code
slug: unbound-force-code
providers:
  - vertex-ai
trigger: |
  event.entity.kind == "work_item"
    && event.transition.kind == "label_changed"
    && event.transition.label.name == "ready-to-code"
    && event.transition.label.action == "added"
timeout_minutes: 30

The harness is thin — it handles plumbing. The methodology lives in the repo's .opencode/ directory, same as always.

Tradeoffs:

Pro	Con
Full local/FullSend parity	Requires a custom sandbox image (OpenCode + uf installed)
No translation or duplication of uf concepts	Goes beyond BYOA's designed-for use case
Slash commands, review council, full pipeline	Heavier image than default fullsend-sandbox
Single source of truth (.opencode/ in the repo)	May need coordination with FullSend team on runtime support

---

Approach B: Full uf Binary in Default Sandbox

Install the uf binary in a custom sandbox image but use FullSend's native agent runtime (not OpenCode). The agent definition references uf as a tool it can call.

Tradeoffs:

Pro	Con
uf CLI available for orchestration	Slash commands don't work natively (no OpenCode runtime)
Can invoke uf commands from agent prompt	Need to rewrite command logic as agent instructions
Standard BYOA pattern	Two systems: uf commands locally, translated prompts in FullSend
	Breaks parity — agent behaves differently locally vs. in container

---

Approach C: Portions (Skill-Based)

Extract the spec-driven workflow as a FullSend skill. The agent inherits from the built-in code agent and gains spec awareness via mounted knowledge:

.fullsend/
├── harness/uf-code.yaml              # base: fullsend code agent + uf skill
├── agents/uf-code.md                 # Thin wrapper with spec gate behavior
└── skills/spec-driven-dev/
    ├── SKILL.md                      # Constitution + phase rules + routing logic
    └── references/
        ├── constitution.md           # Distilled from .specify/memory/constitution.md
        └── workflow.md               # Speckit/OpenSpec routing decision tree

Tradeoffs:

Pro	Con
Lightest touch — works within BYOA's designed-for use case	No parity — agent behaves differently locally vs. in FullSend
No custom image needed	Slash commands don't work (skill is just knowledge, not execution)
Portable — other teams adopt by adding one skill	Must maintain two representations of the same workflow
	Less autonomy — can't run full Speckit pipeline

---

Component Mapping Across Approaches

uf Component	A: OpenCode Runtime	B: uf Binary Only	C: Skill-Based
Slash commands	Work natively	Must be reimplemented as prompts	Distilled into skill
Convention packs	Read automatically	Must be referenced manually	Embedded in skill
Constitution + phase gates	Active (OpenCode reads it)	Referenced by agent prompt	Summarized in skill
Orchestration engine	Full access	CLI available	Delegated to FullSend
Agent personas	All available	Only one (agent definition)	Only code agent
Review council	Available	Available via CLI	Separate FullSend agent
Dewey MCP tools	Needs API server/provider	Needs API server/provider	Out of scope
Local/FullSend parity	Yes	Partial	No

---

Connection to complytime/roadmap#50

RFC: Integrating SpecDrivenDev tooling after AAC Review proposes using OpenSpec as the bridge between ADR approval and implementation. This custom agent is what makes that proposal concrete within FullSend:

• The agent enforces: ADR approved → spec exists → implement
• Teams register the agent via .fullsend/config.yaml
• The routing logic (OpenSpec for tactical, Speckit for strategic) runs natively in Approach A

---

Open Questions

1. Does FullSend's sandbox architecture support running OpenCode as the agent runtime, or is the runtime locked to their built-in agent framework?
2. What's involved in building a custom sandbox image with OpenCode + uf? Image size, build pipeline, version pinning.
3. Does uf need adaptation for headless (sandbox) execution, or do the CLI commands already work non-interactively?
4. How does credential delivery (WIF, GH_TOKEN) interact with OpenCode's configuration inside the sandbox?
5. Should we start with the unbound-force repo as the pilot, then generalize?
6. How does this interact with per-org vs. per-repo FullSend installs?
7. Is there a hybrid path — Approach A for our team, Approach C as a portable "starter" for teams not yet using uf?

---

Security & Production Readiness Findings

After investigation with the FullSend team (via #1260), the following blockers exist before OpenCode can be a production runtime in FullSend:

Security Blockers (FullSend must own — not fixable upstream)

OpenCode's SECURITY.md explicitly states its permission system is a "UX feature, not a security boundary." In headless mode, all permissions are granted by default. The OpenCode project only fixes browser-exploitable RCEs — systemic hardening is out of scope per their threat model.

FullSend must implement compensating controls:

• Environment sanitization — strip secrets before agent starts (pre-script responsibility)
• Command/tool restriction — via OpenShell sandbox policy (landlock, process identity)
• Prompt injection hardening — agent definition level
• Network isolation — via provider profiles (already exists in FullSend)
• Tool-scoping enforcement — OpenCode only supports tool scoping at agent level, not per-skill. FullSend's skill architecture relies on per-skill scoping.

Dependency Chain (Priority Order)

1. Security compensating controls — without this, production use is a non-starter
2. #1935: TranscriptHandler — format-neutral contract needed before any second runtime ships
3. Tool-scoping adapter + agent definition translation — skill/harness compatibility layer
4. #1260 acceptance criteria — sandbox integration, scaffolding, docs

No published timeline exists for the OpenCode alignment workstream.

Revised Approach

Given these findings, full parity (Approach A) is a medium-term target, not an immediate deliverable. The interim path:

• Now: Enforce spec-driven development using FullSend's existing Claude Code runtime (via skill or AGENTS.md-based enforcement)
• Contribute: Help close #1935 (TranscriptHandler) — foundational, non-security, and aligned with our NDJSON parsing experience
• Later: Full OpenCode runtime once security controls are in place

---

Next Steps

• Immediate: Implement spec-driven enforcement using existing Claude Code runtime (skill-based or AGENTS.md)
• Contribute: Engage on #1935 (TranscriptHandler format-neutral contract)
• Track: Monitor FullSend's security compensating controls progress
• Validate: Once OpenCode runtime lands, test full .opencode/ ecosystem in FullSend sandbox
• Document: Adoption path for other teams

[jflowers]

I used an agent to post this. If it sounds authoritative and a command to do it this way that was not intentional. I only mean to share what I discovered.

Investigation Complete — Approach A Confirmed, Execution Plan Below

After a deep investigation of both the FullSend codebase (fullsend-ai/fullsend) and the uf stack, here are the concrete findings and a possible path forward.

---

Key Findings

1. FullSend's runtime is currently hard-locked to Claude Code.

runtime.Resolve() in internal/runtime/registry.go only accepts claude and dummy; any other value returns unknown runtime. Runtime selection happens at the org or per-repo config level (defaults.runtime / runtime), not per-harness — so within a repo, all agents share one runtime. Setting runtime: opencode today would error.

2. OpenCode is explicitly on FullSend's roadmap.

• docs/roadmap.md lists OpenCode under Phase 2 Infrastructure ("Now").
• docs/glossary.md: "Currently, Claude Code and OpenCode are the primary runtime candidates."
• docs/ADRs/0003-org-config-repo-convention.md: config example shows harness: claude-code # or opencode.
• docs/superpowers/specs/2026-07-06-agent-event-stream-rendering-design.md: contains a "Future: opencode Integration" section with a planned parseOpenCodeStream() function mapping OpenCode's ndjson events (tool_use, text, thinking, step_start, step_finish, error) to shared AgentEvent types. This is the contract that issue #1935 is asking for.
• docs/runtimes.md: "When adding a runtime, fill in the security matrix below and register it in runtime.Resolve()."
• Issues #1260 and #1935 track OpenCode alignment.

3. uf already runs fully headless via opencode run.

The council-review-action proves the exact execution model FullSend needs:

opencode run --model "${MODEL}" --format json --file review_prompt.txt \
  -- "Review this PR according to the attached prompt."

• --format json emits ndjson events: {"type":"text","part":{"text":"..."}}
• Auto-discovers .opencode/ agents, commands, packs from the working directory.
• Vertex auth: WIF via GOOGLE_APPLICATION_CREDENTIALS + OPENCODE_CONFIG_CONTENT env var.
• No --dangerously-skip-permissions needed for read-only agents.

4. The Runtime interface is clean and pluggable.

internal/runtime/runtime.go defines:

type Runtime interface {
    Name() string
    System() string
    ConfigDir() string
    WorkspaceDir() string
    EnvExports() []string
    Bootstrap(input BootstrapInput) error
    Run(ctx, RunParams, printer, start, metrics) (exitCode, error)
    ClearIterationArtifacts(sandboxName string) error
}

ClaudeRuntime implements this with ~150 lines. An OpenCodeRuntime is a structurally similar implementation that calls opencode run instead of claude.

5. Security hook gap (acceptable for read-only, must close for write-capable).

Claude Code has PreToolUse/PostToolUse hooks (ClaudeHooksBootstrap) for Tirith, SSRF detection, canary tokens, secret redaction, and unicode normalization. OpenCode has no equivalent hook system — permissions are declarative (agent frontmatter tool booleans + opencode.json bash patterns). Host-side scanners still run (they are runtime-agnostic). This gap is irrelevant for read-only agents (Increments 1–2) but must be closed before the first write-capable agent (Increment 3+).

---

Locked Decisions

Decision	Choice	Rationale
Approach	A — OpenCode + uf as runtime	Only path to full parity
Contribution model	Upstream to fullsend-ai/fullsend	Aligns with #1260/#1935; reusable by PSDev; no fork to maintain
Sequencing	Straight to parity	No throwaway skill MVP; invest directly in the real thing
Dewey/Ollama	Deferred (keyword fallback)	Smaller image, less risk; agents already guard with "if Dewey available, else skip"
Target scope	Full SDD pipeline	Review → address-feedback → specify/opsx → code → forge
Interactive input	Async GH-comment Q&A + resume	AskUserQuestion blocks headless; replaced by status:needs_input + /uf.answer reply
Enforcement	Deterministic uf gate	validation_loop.script + local pre-commit hook; model cannot bypass
Slash command style	/uf.* via comment.body.startsWith() CEL	No /fs- rename; uf-native naming preserved

---

Parity Model

uf's agents/commands/skills/packs live in the repo's committed .opencode/ and are auto-discovered by opencode run. Parity means: same .opencode/ + same opencode run engine = identical behavior. Only three concerns differ by environment:

Concern	Local	FullSend	Adapter
Trigger	opencode TUI / uf CLI	GitHub event → CEL dispatch	harness trigger:
Credentials	uf gateway :53147	Vertex WIF provider	host_files + OPENCODE_CONFIG_CONTENT
Human input	interactive AskUserQuestion	async /uf.answer GH comment	status:needs_input + resume brief

---

Increment Roadmap

Inc	Agent	Why this order	Writes?	Security-hook parity
1	uf-review (Divisor council)	Already proven headless; read-mostly	No	Gap acceptable
2	uf-address-feedback	Introduces async Q&A + resume loop	No (comments)	Gap acceptable
3	uf-specify / uf-opsx + uf gate	Spec creation + enforcement gate	Yes (artifacts)	Required
4	uf-code (cobalt-crush)	First source-writing agent	Yes	Required
5	uf-forge	Multi-agent (runs in ONE sandbox via OpenCode sub-agent delegation; FullSend sees one agent)	Yes	Required

---

Increment 1 — uf-review Execution Detail

Goal: A /uf.review comment (or PR open/synchronize) runs the 9-persona Divisor council via opencode run in a FullSend sandbox and posts a PR review from the host.

Custom Image

ghcr.io/unbound-force/fullsend-opencode:latest — extends the FullSend sandbox base:

FROM ghcr.io/fullsend-ai/fullsend-sandbox:latest
ARG OPENCODE_VERSION=1.18.5
USER root
RUN npm install -g opencode-ai@${OPENCODE_VERSION}
# uf CLI (for `uf gate` in Inc3+); pin + SHA256
RUN curl -fsSL -o /tmp/uf.rpm <release-url> \
 && echo "${UF_SHA256}  /tmp/uf.rpm" | sha256sum -c - \
 && dnf install -y /tmp/uf.rpm && rm /tmp/uf.rpm
USER 1000

Dewey/Ollama intentionally omitted. Multi-arch + digest-pinned per ADR 0036.

OpenCodeRuntime (new file: internal/runtime/opencode.go)

Implements Runtime + TranscriptHandler, mirroring claude.go:

• Name() → "opencode"
• System() → "anthropic" (Vertex-backed)
• ConfigDir() → sandbox.SandboxWorkspace (.opencode/ auto-discovered from repo dir)
• Bootstrap() → mkdir -p .opencode/{agents,skills}, upload harness-declared agent + skills; skip installClaudeHooks (no OpenCode equivalent)
• Run() → buildOpenCodeRunCommand(params) → sandbox.ExecStreamReader() → parseOpenCodeStream() → metrics capture → exit code
• ClearIterationArtifacts() → no-op (Inc1)

Command builder (mirrors council-review-action/run-review.sh):

cd <RepoDir> && set -a; . .env; for f in .env.d/*.env; do . "$f"; done; set +a;
opencode run --format json [--model '<Model>'] --agent '<AgentBaseName>'
  -- 'Review the PR described in ./review_context/review_prompt.txt ...'

Plus parseOpenCodeStream() — the ndjson parser that #1935 asks for. Maps {"type":"text",...} → TextEvent, start/end → session boundaries, step_finish → ResultEvent (token/cost best-effort until #1935 lands).

Registry changes (2 lines):

• registry.go Resolve(): add case "opencode":
• config.go ValidRuntimes(): add "opencode" to the slice

Harness — harness/uf-review.yaml

agent: agents/uf-review.md
role: review
slug: unbound-force-review
description: "uf Divisor council PR review (9 personas) via OpenCode"
image: ghcr.io/unbound-force/fullsend-opencode:latest
model: google-vertex-anthropic/claude-sonnet-4-6
readonly_repo: true

trigger: |
  event.transition.kind == "opened"
  || event.transition.kind == "reopened"
  || event.transition.kind == "synchronized"
  || (event.transition.kind == "comment_added"
      && event.transition.comment.body.startsWith("/uf.review"))

providers: [vertex-ai]

host_files:
  - {src: env/opencode-vertex.env, dest: /sandbox/workspace/.env.d/opencode-vertex.env, expand: true}
  - {src: ${GOOGLE_APPLICATION_CREDENTIALS}, dest: /tmp/.gcp-credentials.json}
  - {src: ${GCP_OIDC_TOKEN_FILE}, dest: /sandbox/workspace/.gcp-oidc-token, optional: true}

pre_script: scripts/pre-uf-review.sh
post_script: scripts/post-uf-review.sh
validation_loop:
  script: scripts/validate-uf-review.sh
  schema: schemas/uf-review-result.schema.json
  max_iterations: 2

env:
  runner:
    GH_TOKEN: ${GH_TOKEN}
  sandbox:
    UF_REVIEW_MODE: council

timeout_minutes: 20
sandbox_timeout_seconds: 600

Agent Definition — agents/uf-review.md

Thin entry point; delegates to the repo's real divisor-* personas:

---
name: uf-review
description: Headless entry to the uf Divisor review council; emits council JSON.
mode: primary
temperature: 0.1
tools: {read: true, write: false, edit: false, bash: false, webfetch: false}
---
Read ./review_context/review_prompt.txt (PR metadata + unified diff).
Run the Divisor council: for each persona in .opencode/agents/divisor-*.md,
apply its checklist and the severity pack (.opencode/uf/packs/severity.md).
Aggregate to ONE JSON object matching schemas/uf-review-result.schema.json:
{status, verdict, summary, inline_comments[], provenance}.
Print ONLY that JSON as the final message.

Output Schema — schemas/uf-review-result.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["status", "summary", "inline_comments"],
  "properties": {
    "status": {"enum": ["complete", "needs_input", "error"]},
    "verdict": {"enum": ["approve", "request_changes", "comment"]},
    "summary": {"type": "string"},
    "inline_comments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["path", "line", "severity", "body"],
        "properties": {
          "path": {"type": "string"},
          "line": {"type": "integer"},
          "severity": {"enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]},
          "persona": {"type": "string"},
          "body": {"type": "string"}
        }
      }
    },
    "pending_question": {
      "type": "object",
      "properties": {
        "id": {"type": "string"},
        "prompt": {"type": "string"},
        "options": {"type": "array", "items": {"type": "string"}}
      }
    },
    "provenance": {
      "type": "object",
      "required": ["agent", "model", "commit", "timestamp"]
    }
  },
  "allOf": [{
    "if": {"properties": {"status": {"const": "needs_input"}}},
    "then": {"required": ["pending_question"]}
  }]
}

pending_question/needs_input are unused in Inc1 but defined now so Inc2 needs no schema change. provenance satisfies Constitution III (Observable Quality).

Scripts

pre-uf-review.sh (host, before sandbox): Parse NormalizedEvent JSON → owner/repo/PR number; gh pr view + gh pr diff → write review_context/review_prompt.txt and review_context/pr.json into the target repo working dir. Keeps creds on host; agent stays read-only.

validate-uf-review.sh (host, validation_loop): Extract the last text event from the tee'd ndjson stream → write agent-result.json → structural check via schema → semantic checks (verdict present iff status=complete; severities valid). Non-zero exit triggers FullSend's re-run with feedback (max 2 iterations).

post-uf-review.sh (host, after sandbox): Discover iteration-*/output/agent-result.json (last wins) → map verdict → post PR review via gh api repos/{owner}/{repo}/pulls/{n}/reviews with inline comments filtered to diff lines; fallback to gh pr comment if no inline comments. Write GITHUB_STEP_SUMMARY severity table.

Dispatch

Per-repo install (custom-harness routing requires per-repo, not per-org). /uf.review matched via comment.body.startsWith in the CEL trigger — no /fs- rename needed.

Acceptance Test

fullsend run uf-review --fullsend-dir .fullsend --target-repo . --env-file .env.local must produce the same council JSON as local /uf.review-council. That equivalence is the Increment 1 gate.

---

Phase 0 Spikes (GO/NO-GO before building Increment 1)

1. opencode run inside fullsend-sandbox — Vertex WIF via OPENCODE_CONFIG_CONTENT + GOOGLE_APPLICATION_CREDENTIALS → returns council JSON. Highest-risk; council-review-action strongly implies GO.
2. .env.d/*.env sourcing — confirm the sandbox sources it, or source explicitly in buildOpenCodeRunCommand.
3. OutputPath stream file — confirm location/availability for the validation script.
4. OpenCode ndjson token/cost fields — for RunMetrics (partial metrics acceptable for Inc1).

---

Spec-Driven Enforcement — uf gate (Cross-Cutting, Starts Inc3)

New headless subcommand: uf gate --phase <specify|plan|implement|review|pr> --format json. Exit non-zero blocks. Enforces: spec+plan+tasks exist/approved before implement; review PASS before PR; coverage strategy present (Constitution IV); no direct main commits. Wired as validation_loop.script in write-capable harnesses and as a local pre-commit/pre-PR hook → identical gate both places.

---

Async Q&A Resume (Inc2)

At spec-driven phase gates (never mid-reasoning), if input is needed:

1. Agent emits status:needs_input + pending_question and a resume brief committed to the working branch as state.json (current phase, decisions made, pending decision, next action).
2. post_script posts the question as a GH comment.
3. A /uf.answer <text> reply re-triggers the harness; pre_script feeds the answer + resume brief back in.

Cold resume from the checkpoint is the default. Warm resume (OpenCode --session/--continue + single-session export/import from opencode.db) is a separate spike, never a dependency.

---

Upstream Contribution Sequence

1. Comment on #1935 (ndjson event contract) offering parseOpenCodeStream + OpenCodeRuntime; align on #1260.
2. PR 1: OpenCodeRuntime + registry + ValidRuntimes + parseOpenCodeStream + unit tests.
3. PR 2: docs (docs/runtimes.md opencode row + security matrix noting the hook gap) + the fullsend-opencode image.
4. Land the pilot in the unbound-force repo; use it as the reference BYOA for PSDev.

---

Open Risks

Risk	Mitigation
Security-hook gap (no OpenCode PreToolUse/PostToolUse)	Fine for read-only Inc1–2; must close before write-capable Inc4 — options: OpenCode plugin shim, wrapper-enforced tool allowlisting, or host-side diffing of sandbox writes. Needs its own spike.
Runtime is per-repo, not per-harness	Pilot repo runs all agents on OpenCode (fine for uf-native repo). Mixed-runtime repos need an upstream per-harness override.
--format json token/cost fidelity unknown	Metrics partial until #1935 lands; acceptable for Inc1.
Interactive commands never behave identically headless	By design — async Q&A replaces them. Set this expectation with PSDev.

---

Answers to Original Open Questions

1. Does FullSend support OpenCode as runtime? Not today — runtime is locked to Claude + dummy. But OpenCode is on the Phase 2 roadmap (#1260, #1935) with a planned parseOpenCodeStream(). We will contribute the implementation upstream.
2. Custom image? Extend fullsend-sandbox + npm install opencode-ai + dnf install uf. Dewey/Ollama deferred.
3. Headless adaptation? opencode run --format json already works headless (proven by council-review-action). Interactive AskUserQuestion replaced by async GH-comment Q&A.
4. Credential delivery? OPENCODE_CONFIG_CONTENT env var (Vertex provider config) + GOOGLE_APPLICATION_CREDENTIALS via host_files — mirrors council-review-action exactly.
5. Pilot repo? Yes, unbound-force — per-repo install with runtime: opencode.
6. Per-org vs per-repo? Per-repo (custom harness routing requires it per ADR 0044/0061).
7. Hybrid? No throwaway skill MVP. Straight to parity. Other teams adopt by pointing to the same OpenCodeRuntime upstream + their own .opencode/ directories.

I used an agent to post this. If it sounds authoritative and a command to do it this way that was not intentional. I only mean to share what I discovered.

[jflowers]

Revised execution plan — uf as a FullSend BYOA (opencode runtime)

Update to the Aug-5 execution plan above. Re-verified against the current state of both repos, the merged opencode PRs, @beatrizmcouto's story breakdown (#508–#518), @sonupreetam's per-repo onboarding spike (complytime-labs/stale-review-test), and the FullSend getting-started docs. Approach A (uf-as-OpenCode-runtime, full parity) is unchanged.

Confirmed direction

• Approach A — same committed .opencode/ drives uf locally and in FullSend; contribute OpenCodeRuntime upstream, no fork; straight to parity.
• Per-repo install (ADR 0033; per-org deprecated by ADR 0044).
• Runtime identity: Name()=opencode, System()=anthropic (Vertex-backed). Bug to fix: stub System() returns "opencode" (opencode.go:26) — must be "anthropic" per claude.go:27.
• Image: ghcr.io/unbound-force/fullsend-opencode (digest-pinned, cosign-signed) extending fullsend-sandbox; opencode-ai pinned (start 1.18.5); uf from release tarball + SHA256 (base is apt/Ubuntu, no .deb); non-root (USER sandbox).

Already landed upstream

• PR #6035 — stub runtime registration (registry.go Resolve + opencode.go skeleton) ✅
• PR #6147 — ndjson stream parser (parseOpenCodeStream) ✅
• Cross-link posted on fullsend#1260 — connecting the upstream tracking epic to our contribution story #510.

Stories

Story	Title	Size	Depends on
#509	Prove OpenCode runs headless (Phase 0 GO/NO-GO)	M	—
#510	Contribute OpenCodeRuntime	L	#509 GO
#511	Digest-pinned fullsend-opencode image	M	parallel w/ #510
#519	Onboard unbound-force (per-repo) (new)	M	O0–O2 none; O3 → #510
#512	Divisor council review (Inc1)	M	#509, #510, #511, #519
#513	Resume from comment answers (Inc2) + trace fidelity	M	#512, #510
#514	Headless uf gate	M	after #509; before Inc3–5
#515	Close security-hook gap	L	before Inc3
#516	Create specs (Inc3)	M	#513, #514, #515
#517	Implement specs (Inc4)	M	#516, #514, #515
#518	uf-forge multi-agent (Inc5)	L	#517, #514, #515
#508	Parent — uf in a FullSend BYOA container	XL	all above

What changed since Aug 5

1. Re-added Phase 0 spike ([Story] Prove OpenCode runs headless in the FullSend sandbox #509) as an explicit GO/NO-GO gate — no building on unproven runtime.
2. Added missing onboarding story #519 — per-repo FullSend enrollment (mint, inference, GitHub app, github setup, runtime flip). O0–O2 can start immediately; O3 gated on [Story] Contribute OpenCodeRuntime to FullSend #510. Validated against @sonupreetam's complytime-labs/stale-review-test spike.
3. Locked image namespace + hardening — ghcr.io/unbound-force/fullsend-opencode, digest-pinned parent, cosign-signed, uf installed from release tarball + SHA256 (base is Ubuntu/apt, no .deb), USER sandbox. Generic upstream opencode-only base deferred as follow-up.
4. Pinned uf gate contract — uf gate --phase <specify|plan|implement|review|pr> --format json; wired as validation_loop.script on all write-capable harnesses.
5. Sequenced security-hook gap ([Story] Close the OpenCode security-hook gap before write-capable agents #515) before any write-capable increment — read-only Inc1–2 can proceed without it.
6. Pilot on locally-built fullsend from the PR1 (OpenCodeRuntime) branch — config.go:352 rejects --runtime opencode today; pilot uses a branch build that includes ValidRuntimes() update.
7. fullsend#1935 closed (2026-08-12) without the TranscriptHandler redesign landing in code. [Story] Contribute OpenCodeRuntime to FullSend #510 ships an interim output.jsonl tee approach. Full-fidelity trace extraction (opencode export <sessionID>) and the AgentEvent vs TraceRecord IR design question (em-redhat's comment) are now scoped in #513. Cross-link posted on fullsend#1260.

Implementation detail

Each story body (#508–#518 + #519) now includes an appended "Implementation Notes" section with code sketches, harness YAML, Containerfile, host scripts, CLI signatures, schema drafts, operational references from the onboarding spike, and a troubleshooting playbook. The full working plan is maintained in opencode-fullsend-byoa-plan.md.

Key risks

Risk	Severity	Mitigation
Security-hook gap (no PreToolUse/PostToolUse in opencode)	Blocker for Inc3+	Acceptable for read-only Inc1. #515 must close before writes.
Mint enrollment is manual/blocking	Medium	Start O0 early; fallback: self-host.
Runtime flip gated on A6 in built binary	Medium	Pilot uses PR1-branch build; O0–O2 independent.
Cosign runner verification not enforced today	Low	Proactively sign; fold trust-policy check into Phase 0.
OpenCode version pinning / ndjson fidelity	Medium	Pin in image; re-verify on GA release.

---

@sonupreetam @beatrizmcouto — feedback welcome. The plan is ready for Phase 0 (#509) and Onboarding (#519) to start in parallel.

[yvonnedevlinrh]

Review Feedback

Its a thorough RFC and execution plan and the direction is sound — Approach A (full parity), incremental rollout, and security-before-writes ordering are all correct calls.

I've reviewed the Discussion alongside the 11 child stories (#509–#519) and the Divisor triage panel results. Three items need resolution at this level before the later increments can be scoped:

1. Terminology gap

"FullSend", "BYOA", "harness", "validation_loop.script", "fullsend-opencode", and related terms have zero presence in the unbound-force codebase. The triage panel flagged this independently on every single child story. This isn't blocking for early stories (#509, #514), but it creates a friction multiplier across the entire backlog.

Request: Add a glossary section to this Discussion or to the epic (#508) that maps each term to its definition and links to external documentation. This unblocks downstream spec work across all stories.

2. Phantom artifact references

Several stories reference artifacts that do not exist:

• ADR 0036 — referenced in [Story] Publish a digest-pinned fullsend-opencode sandbox image #511 as the authority for digest pinning, but docs/decisions/ contains only ADR 001
• docs/runtimes.md — referenced in [Story] Publish a digest-pinned fullsend-opencode sandbox image #511 and [Story] Close the OpenCode security-hook gap before write-capable agents #515 as in-scope documentation, but the file does not exist
• "Inc1 schema fields" (pending_question, needs_input) — referenced in [Story] Resume FullSend agents from GitHub comment answers #513, but no schema in schemas/ contains these fields

Request: Either create these artifacts ahead of the stories that reference them, or update the stories to state these are net-new
deliverables rather than existing references.

3. --pure mode vs. forge coordination (Inc5 blocker)

The triage panel identified a fundamental conflict in #518: --pure mode disables all MCP tools for security isolation, but forge
coordination depends on Replicator MCP tools (comms_init, comms_reserve, hivemind_*). These are mutually exclusive — Inc5
cannot work as currently designed.

This isn't a clarification — it's an architectural question that needs a design proposal. Options might include:

• Selective MCP tool allowlisting (permit coordination tools, deny others)
• A different isolation model for multi-agent (filesystem-based coordination instead of MCP)
• Accepting that forge-in-FullSend requires a fundamentally different approach than local forge

Request: Address this in the Discussion before #518 enters the spec pipeline.

Additional observations

• [Story] Enforce spec-first with headless uf gate #514 (uf gate) received unanimous VALID from the triage panel and has uf doctor as a clear structural precedent. Recommend this enters the spec pipeline first alongside [Story] Prove OpenCode runs headless in the FullSend sandbox #509.
• Shell injection in [Story] Contribute OpenCodeRuntime to FullSend #510: The fmt.Sprintf("cd %s && . %s && opencode run --model %s ...") pattern is a textbook injection vector — flagged HIGH by 3/5 agents. Must use exec.Command with argument separation.
• /uf.answer injection in [Story] Resume FullSend agents from GitHub comment answers #513: Untrusted GitHub comment content reaching agent execution context is a significant attack
  surface. Needs input validation, length limits, and sanitization in the spec.
• Coverage strategies: Constitution IV requires coverage strategy in the implementation plan. This was flagged on nearly every story
  but is a spec-phase deliverable, not an issue-level requirement. Each story's spec/plan should include it before implementation.

[jflowers]

Response to review feedback

@yvonnedevlinrh — thank you for the thorough review. All three items have been addressed, and the four observations are acknowledged with specific commitments below.

---

1. Terminology gap — resolved

A Glossary section has been added to the epic (#508) covering all FullSend/BYOA terms (FullSend, BYOA, harness, validation_loop.script, fullsend-opencode, runtime/OpenCodeRuntime, OpenShell, mint, inference/WIF, sandbox_hooks/Tirith, TranscriptHandler/ndjson, Divisor council, uf gate, forge). This is the canonical reference — each term links to the relevant external doc or child story.

2. Phantom artifact references — clarified

Two of the three references are not phantom — they are cross-repo references to artifacts in the fullsend repo (fullsend-ai/fullsend):

Reference	Actual location	Status
ADR 0036	fullsend/docs/ADRs/0036-agent-execution-sandbox.md	Existing fullsend decision record, referenced as external authority
docs/runtimes.md	fullsend/docs/runtimes.md	Existing fullsend doc; stories deliver net-new upstream edits (OpenCode column in security matrix)
pending_question / needs_input	Does not exist yet	Net-new fields in the uf-review-result schema, delivered by #512 and consumed by #513

The issue was labeling, not existence. All three stories have been updated:

• #511 and #515: ADR 0036 and runtimes.md now explicitly labeled as fullsend-repo artifacts with links
• #513: pending_question/needs_input now explicitly marked as net-new schema fields from [Story] Run the Divisor council review in FullSend #512

3. --pure mode vs. forge coordination — design direction recorded

Confirmed real. --pure is a blanket MCP disable, and forge coordination needs Replicator's comms_*/hivemind_* tools. These are mutually exclusive.

Recommended direction (recorded on #518): For Inc5 only, drop --pure and ship a scoped opencode.json / OPENCODE_CONFIG_CONTENT that enables only the Replicator MCP server (Dewey and all other external MCP disabled) plus permission denials. This achieves selective allowlisting rather than all-or-nothing control.

This widens the tool surface vs. Inc1-4, so it is explicitly gated on #515 (security-hook gap closure). A short spike is needed before #518 enters the spec pipeline to confirm OpenCode's per-server and per-tool MCP granularity. Fallback if granularity is insufficient: filesystem-based coordination (no MCP).

Since #518 is the last increment and already depends on #515, there is runway to resolve this.

---

Additional observations — commitments

Observation	Response	Updated
#514 sequencing — unanimous VALID, uf doctor precedent	Agreed. #508 now notes #514 may enter spec pipeline alongside #509.	#508
Shell injection in #510 — fmt.Sprintf("cd %s && …") flagged HIGH	Valid concern. However, exec.Command with argv separation is not applicable here — the sandbox boundary is openshell sandbox exec -- sh -c <command> (sandbox.go:684), which requires a shell string. The correct fix is shell-escaping + input validation, mirroring the established pattern in claude.go:297,314,318,322,326 (single-quote wrapping + '\'' escape + charset allowlist). Security requirement added to #510.	#510
/uf.answer injection in #513 — untrusted comment content	Valid. Input sanitization requirements added: length cap, control-char stripping, data-not-instructions treatment, shape validation, audit trail.	#513
Coverage strategies (Constitution IV)	Agreed — this is a spec-phase deliverable, not an issue-level AC. Noted in #508 process section: each story's spec/plan includes coverage strategy before implementation.	#508

[jflowers]

Bringing up a critical blind spot we need to account for in this RFC: agent prompt and definition files across uf currently rely on direct gh CLI execution.

Once we drop these agents into a network-isolated FullSend BYOA container (uf sandbox / OpenShell) where raw credentials are stripped and egress is blocked, any agent instruction telling it to run gh pr create or gh issue create is going to hit a wall.

Since this was initially overlooked, we need a clean way to bridge local execution parity with strict container isolation without forcing a massive, painful rewrite of every agent prompt. Here are three architectural paths we could take to solve this:

1. The Intercepting gh Shim (Client-Side Emulation)

Drop a lightweight custom gh script or binary into the container's PATH.

• Local Mode: If running in an unconstrained local context, it can safely wrap requests using a local dev token.
• FullSend Pipeline Mode: It detects strict isolation and automatically serializes the intent into a local markdown/JSON payload (.uf/staged_pr.json) for host-side execution, preventing hard failures while maintaining isolation.

2. Host-Mounted Unix Domain Socket (uf gateway Relay)

If we want agents to have interactive GitHub integration without leaking credentials or opening raw internet ports inside the container:

• Mount a restricted Unix domain socket (/var/run/uf-gateway.sock) from the host.
• The agent's gh commands forward payloads over the socket to a host-side uf gateway daemon running with proper authentication. The gateway validates the request, hits GitHub, and returns the response.
• In true FullSend production pipelines, the socket mount is omitted, cleanly falling back to artifact-staging mode.

3. OpenCode Native Tool Definitions (Long-Term Clean Break)

Relying on raw shell-scripting via CLI tools is inherently fragile to agent hallucinations. Long-term, we should abstract this out of prompt text entirely and into OpenCode native tool definitions (e.g., github.create_pull_request(...)).

• The tool handler checks the runtime context: direct execution locally vs. async intent-generation inside FullSend.

---

Thoughts on how we want to tackle this? The intercepting shim (#1) or gateway socket (#2) look like the quickest ways to keep local DX smooth while we lock down the container security boundary.