DeepSeek Harness Capability Seam Architecture: 10x Extensibility Over Tool Plugins

1 Pain Point: Implicit Sub-Agent Boundaries

Traditional agent frameworks (e.g., Claude Code, Codex) treat sub-agent spawning, nesting depth limits, and session continuation as soft constraints defined in prompt descriptions. The model must interpret these rules semantically, leading to unpredictable behavior: unauthorized sub-tasks, uncontrolled nesting, and context leakage across delegation chains. No runtime enforcement exists.

2 Skeleton: Everything Is a Plugin, Including the Agent Loop

DeepSeek Harness (dsh) builds on the Cordis kernel, which only manages plugin loading, unloading, and dependencies. All capabilities—model adapters, tool registry, session logging, and even the agent main loop—are plugins. No privileged core modules exist; swapping models or replacing the entire loop requires only adding or replacing plugins.

Configuration uses a Profile + Bundle layering: dsh-base (model adapter, tools, persistence, sandbox, approval), dsh-web-app (browser interaction), dsh-headless (one-shot runner). Patches target rows by ID for whole-line replacement.

2.1 Capability Seam Core Concept

A Capability Seam consists of three parts:

Service Definition – interface declaration (e.g., ctx.shell, ctx.subagents)

Service Provider – concrete implementation (e.g., bash-local, bash-sandbox, pwsh-local)

Consumer – caller side, typically a tool exposed to the model (e.g., tool-bash)

All three must be present for the capability to register. Sub-agents are built as one such seam, parallel to shell, filesystem, persistence, etc.

2.2 Traditional Pluggable Tool vs. Capability Seam Architecture

The key differences across dimensions:

Plug Point : Traditional tools plug at the ToolSpec layer; DSH capability seams plug at the underlying capability contract ( ctx.*) layer, with the tool as just a consumer.

Model Awareness : Traditional tools require the model to choose among different tool entries for different implementations; DSH presents a single call entry, providers are transparent to the model.

Dependency : Traditional tool handlers bind directly to execution implementations; DSH consumers depend only on the abstract Definition, not concrete Providers.

Replacement : Traditional tools require adding/removing tools and changing prompts/tool lists; DSH switches providers via config, leaving tool code and prompt unchanged.

Cascading : Traditional tools have no cascade; DSH supports cascade: switching one seam auto-switches downstream dependents.

Coexistence : Traditional tools register multiple isolated tool entries; DSH registers multiple providers under the same contract, selectable by name.

Scope : Traditional tools cover only model-initiated actions; DSH covers LLM calls, shell, filesystem, sub-agents, persistence, approval—all runtime capabilities.

In short: traditional tools plug actions shown to the model ; capability seams plug the underlying execution capabilities that power those actions .

3 Why Sub-Agent Belongs to a Seam, Not the Main Loop

3.1 Traditional Approach: Sub-Agent as a Loop Tool

// Traditional: Agent tool registered alongside bash/edit
tools.add({
  name: 'Agent',
  desc: 'Delegate sub-task, optional subagent_type',
  call: (args) => spawn(args.subagent_type, args.prompt),
});
// Model issues tool call; result fed back as tool result next turn

Shortcomings: all boundary control (when to split, nesting depth, output shape, session continuity) relies on model self-discipline via description text. No interception mechanism exists; nesting runaway and context crosstalk are common.

3.2 DSH Approach: Sub-Agent as an Independent Seam

Mirroring the shell design: dsh-shell defines contract, dsh-bash-local / dsh-bash-sandbox provide implementations, dsh-tool-bash exposes to model. Sub-agent uses ctx.subagents seam with multiple providers registered by name:

spawn-in-process : New agent in same process; does not inherit parent context.

fork-in-process : Fork in same process, inherits completed turn prefix; inherits seed info.

acp : Remote agent via Agent Client Protocol; does not inherit parent context.

codex : Launches codex app-server --stdio; no parent conversation copy.

claude-code : Calls @anthropic-ai/claude-agent-sdk with persistSession:false; no parent conversation copy.

dsh-sdk : DSH custom JSON-RPC SDK; inheritance per descriptor config.

Key difference from shell: shell allows only one active executor; sub-agent supports multiple providers coexisting under ctx.subagents map. The framework defines the delegation protocol but leaves implementation choice to the user.

4 Four Boolean Capability Flags: Fail-Loud, No Silent Degradation

Each provider must declare capabilities at startup (from packages/subagent/src/types.ts):

interface SubagentCapabilities {
  readonly outputSchema: boolean  // structured output support
  readonly depthLimit: boolean    // respects delegation depth limit
  readonly toolFilter: boolean    // can restrict child tool set
  readonly persona: boolean       // can assign independent persona
}

If a parent delegation requests a capability the provider lacks, dsh throws SubagentError('UNSUPPORTED_CAPABILITY') at startup— fail loud, no silent degradation . Contrast with Claude Code: model reads description, assumes capability, delegates, then receives low-quality natural language output because the child actually lacks structured output or tool filtering. Root-cause debugging becomes time-consuming.

5 Three Harness Frameworks: Design Philosophy Comparison

Comparison across key dimensions:

Sub-agent Model : Claude Code uses Agent tool + subagent_type, single-process, model decides spawn; Codex uses app-server stdio sandbox process, approval-policy driven; DSH uses named provider registry, multi-provider coexistence, upfront capability negotiation.

Boundary Authority : Claude Code relies on model via prompt/description; Codex uses product policy + approval flow; DSH uses provider capability declaration + startup fail-loud verification.

Isolation : Claude Code uses same process, separate context; Codex uses process isolation + sandbox; DSH allows provider-chooseable: in-process spawn/fork + remote ACP + external product processes.

Depth Control : Claude Code uses soft constraint via prompt; Codex uses product-side control; DSH persists delegationDepth and enforces maxDepth hard rejection.

Continuable Sub-agent : Claude Code does not support; Codex does not support (ephemeral instances); DSH supports continuable + Activation + followup/interrupt/report cold resume.

Cross-Product Delegation : Claude Code cannot delegate to Codex; Codex cannot delegate to Claude Code; DSH has built-in codex and claude-code providers, supporting mutual delegation.

Three notable differences:

Boundary authority hardens from model interpretation → product approval → provider contract verification.

Continuable sub-agents are unique to DSH, addressing real long-running task needs (follow-up questions, resumption) at the cost of added continuation-manager complexity.

Cross-product delegation is disruptive: DSH wraps competing products (Codex, Claude Code) as callable backends under a single orchestration layer.

6 Architectural Summary

Most frameworks stop extensibility at the tool layer—adding capability means adding a tool definition. This works at small scale but maintenance cost explodes as delegation chains deepen and execution targets multiply.

Capability Seam architecture decouples the call entry from the underlying implementation. The model invokes a stable contract; the execution backend switches via configuration without prompt or caller-code changes. Applied to sub-agents, it solves the core pains of multi-layer delegation: boundary loss of control, unverifiable capabilities, and non-resumable sessions.

For large-scale multi-engine agent orchestration and cross-platform sub-task delegation, this contract-first, multi-provider coexistence model eliminates entire classes of latent bugs that surface only late in production.