docs(adr): subagent harness schema and sandboxed execution lifecycle

[maruiz93]

What happens

There is no ADR covering how subagents should be defined, spawned, and executed in isolated sandboxes. The design decisions — which harness fields apply to subagents, how spawn-time parameters work, how the output contract is defined, and how the parent discovers and invokes subagent profiles — are undocumented.

What should happen

An ADR should be written covering:

• Which existing harness fields apply to subagents and which don't
• New fields needed: params (spawn-time parameters), output (result contract with schema + files), subagent_harnesses (parent-side profile declarations)
• The fullsend subagent run lifecycle and how it differs from fullsend run
• How the parent agent discovers available subagent profiles and their input/output contracts
• How subagent providers are scoped independently from the parent
• The fullsend-agent CLI tool as the sandbox-side interface

Context

ADR 0020 established that each agent step gets its own sandbox. #3978 tracks the implementation gap. This ADR captures the design decisions needed before implementation can begin.

A draft design is available in the #3978 discussion.

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 9:24 AM UTC · Completed 9:28 AM UTC
Commit: e8381e3 · View workflow run →

[fullsend-ai-triage]

Triage Summary

This is a well-scoped documentation task requesting a new ADR to formalize the subagent harness schema and sandboxed execution lifecycle design. The scope is clearly defined with six topics to cover, and a detailed draft design already exists in the #3978 discussion comments.

Scope

The ADR should cover:

1. Which existing harness fields apply (and don't apply) to subagents
2. New fields: params, output, subagent_harnesses
3. The fullsend subagent run lifecycle and how it differs from fullsend run
4. Parent-side discovery of available subagent profiles and their contracts
5. Independent subagent provider scoping
6. The fullsend-agent CLI as the sandbox-side interface

Starting Material

The draft design in the #3978 discussion proposes a host API server + fullsend-agent CLI architecture with a clear separation between the parent sandbox (which uses the CLI to invoke subagents) and child sandboxes (which run with scoped policies and providers). This design can serve as the Decision section's foundation.

Implementation Dependencies to Document

The ADR's Consequences section should note the implementation prerequisites identified in #3978:

• Host-side API servers for sandboxed agents #879 — Host-side API servers (ADR 0046 pattern)
• Provider and profile definitions cannot be resolved from URL-referenced base harnesses #2672 — Portable provider resolution from URL-referenced base harnesses
• PR fix(agents): There are no subagent "types"; they don't compose #2098 — Subagent definition fix (must land before implementation begins)

These block the implementation, not the ADR writing itself.

Recommended Approach

Follow the writing-adrs skill (skills/writing-adrs/SKILL.md) for template and process. Update docs/architecture.md in the same PR per the skill's guidance.

Test plan:
- ADR follows standard template (Title, Status, Context, Decision, Consequences)
- All six topics from the issue are covered
- docs/architecture.md is updated to reflect the new decision
- make lint passes

---

Labels: This is a documentation task requesting a new ADR, touching the harness and sandbox components.

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 9:28 AM UTC · Completed 9:41 AM UTC
Commit: e8381e3 · View workflow run →

[maruiz93]

@ifireball I would like to continue here the discussion you started in #3988 (comment)

(I'm sorry I wasn't monitoring that adr because I didn't expect code agent to create it)

I would like to expose why I think it's useful to run subagents in a separate sandbox.

Triage is a good example, you want to, for example, check stuff linked in the issue from external repos (let's say), so the triage agent should be able to read that, or even external websites in general.
Then, I would expect ideally for the outcome of this subagent to be validated before it goes to the main agent. We also might want to provide different tools (as in a different image) for different subagents, or even maybe different env variables.

This doesn't mean that I want to remove the posibility of having subagents like we are doing right now, but if we have somehow a subagent defined and want for example to use tools like the dynamic workflows in claude or others, I would like to have the possibility of making each agent of the coordinated workflow have its own harness if we want to.