Skip to main content

Subagent Integration

Integrate Treeship attestations with Claude Code subagents to create verified multi-agent workflows where each agent’s work is cryptographically attested.

Why Subagent Attestation?

When multiple agents work on a task:
ChallengeSolution
Who did what?Each subagent attests its own work
Can I trust the handoff?Verify previous agent’s attestation
What tools were used?Tool usage recorded in attestation
When did work happen?Cryptographic timestamps

Architecture Patterns

Pattern 1: Attesting Subagent

Create a specialized subagent whose job is to create attestations for the main agent’s work. .claude/agents/attester.md:
---
name: attester
description: Creates cryptographic attestations of completed work. Use after significant accomplishments.
tools:
  - treeship_attest
  - treeship_verify
  - treeship_get_agent
---

You are an attestation specialist. When invoked:

1. Analyze what work was just completed
2. Create a comprehensive attestation including:
   - Clear action description
   - Files modified/created
   - Tools that were used
   - Summary of changes

Always use the `treeship_attest` tool with complete information.
Format the action as: "[Verb] [what] for [why/context]"

Example good actions:
- "Implemented user authentication with JWT tokens"
- "Fixed SQL injection vulnerability in search endpoint"
- "Refactored database layer to use connection pooling"
Usage in main agent:
"Complete the authentication feature, then use the attester agent to record the work"

Pattern 2: Self-Attesting Subagents

Each specialized subagent attests its own work before returning results. .claude/agents/security-reviewer.md:
---
name: security-reviewer
description: Security code review specialist. Reviews code for vulnerabilities.
tools:
  - Read
  - Grep
  - Glob
  - treeship_attest
---

You are a security review specialist. 

After completing each review:
1. Document findings
2. Create attestation with `treeship_attest`:
   - agent: "security-reviewer"
   - action: "Security review of [component]: [status]"
   - Include files reviewed and issues found in summary

Your attestation serves as a security audit record.
.claude/agents/test-runner.md:
---
name: test-runner
description: Runs test suites and reports results. Use for testing changes.
tools:
  - Bash
  - Read
  - treeship_attest
---

You are a test execution specialist.

After running tests:
1. Analyze results
2. Create attestation with `treeship_attest`:
   - agent: "test-runner"  
   - action: "Test suite [passed/failed]: [summary]"
   - Include test command and pass/fail counts

Your attestation proves tests were run and records results.

Pattern 3: Handoff Verification

Verify previous agent’s work before continuing. .claude/agents/backend-dev.md:
---
name: backend-dev
description: Backend API developer. Implements server-side features.
tools:
  - Read
  - Write
  - Bash
  - Grep
  - treeship_attest
  - treeship_verify
  - treeship_list_attestations
---

You are a backend developer.

**Before starting work:**
If continuing from another agent's work:
1. Use `treeship_list_attestations` to see recent work
2. Use `treeship_verify` to confirm the handoff attestation
3. Only proceed if verification shows `valid: true`

**After completing work:**
Create attestation with `treeship_attest` documenting:
- What you built
- API endpoints created
- Database changes
- Handoff notes for the next agent

Claude Agent SDK Integration

For programmatic subagent definitions with the Claude Agent SDK:

TypeScript Example

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Build a user dashboard and verify all work",
  options: {
    allowedTools: ["Read", "Write", "Bash", "Grep", "Glob", "Task",
                   "treeship_attest", "treeship_verify", "treeship_list_attestations"],
    agents: {
      "frontend-dev": {
        description: "Frontend React developer. Builds UI components.",
        prompt: `You are a frontend developer specializing in React.

After completing components:
1. Test they render correctly
2. Create attestation:
   treeship_attest(
     agent: "frontend-dev",
     action: "Built [component names]",
     files_created: [list of files],
     tools_used: ["Read", "Write"]
   )`,
        tools: ["Read", "Write", "Grep", "Glob", "treeship_attest"],
        model: "sonnet"
      },
      
      "backend-dev": {
        description: "Backend API developer. Implements server endpoints.",
        prompt: `You are a backend developer.

Before starting: Verify any frontend handoff attestations.
After completing: Attest your API work.`,
        tools: ["Read", "Write", "Bash", "Grep", 
                "treeship_attest", "treeship_verify"],
        model: "sonnet"
      },
      
      "integrator": {
        description: "Integration specialist. Connects frontend to backend.",
        prompt: `You are an integration specialist.

1. Verify both frontend and backend attestations exist
2. Connect the pieces
3. Attest the integration work`,
        tools: ["Read", "Write", "Grep",
                "treeship_attest", "treeship_verify", "treeship_list_attestations"],
        model: "sonnet"
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Python Example

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Build a user dashboard and verify all work",
        options=ClaudeAgentOptions(
            allowed_tools=[
                "Read", "Write", "Bash", "Grep", "Glob", "Task",
                "treeship_attest", "treeship_verify", "treeship_list_attestations"
            ],
            agents={
                "frontend-dev": AgentDefinition(
                    description="Frontend React developer",
                    prompt="""You are a frontend developer.
After completing work, attest with treeship_attest.""",
                    tools=["Read", "Write", "Grep", "treeship_attest"],
                    model="sonnet"
                ),
                "code-reviewer": AgentDefinition(
                    description="Code review specialist",
                    prompt="""Review code and attest your findings.
Include security issues and recommendations in the attestation.""",
                    tools=["Read", "Grep", "Glob", "treeship_attest"],
                    model="sonnet"
                )
            }
        )
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Workflow: Verified Feature Development

Complete workflow with attestation at each stage:
┌─────────────────┐
│  Main Agent     │
│  Coordinates    │
└────────┬────────┘


┌─────────────────┐     ┌─────────────────────┐
│ frontend-dev    │────▶│ Attest: UI complete │
│ Build UI        │     │ Files: 5 components │
└────────┬────────┘     └─────────────────────┘


┌─────────────────┐     ┌─────────────────────┐
│ backend-dev     │────▶│ Attest: API ready   │
│ Verify + Build  │     │ Endpoints: 3 routes │
└────────┬────────┘     └─────────────────────┘


┌─────────────────┐     ┌─────────────────────┐
│ code-reviewer   │────▶│ Attest: Review done │
│ Security check  │     │ Issues: 0 critical  │
└────────┬────────┘     └─────────────────────┘


┌─────────────────┐     ┌─────────────────────┐
│ test-runner     │────▶│ Attest: Tests pass  │
│ Run tests       │     │ Coverage: 85%       │
└────────┬────────┘     └─────────────────────┘


┌─────────────────┐
│  Main Agent     │
│  Deploy + Final │
│  Attestation    │
└─────────────────┘

Verification Page

After the workflow, all attestations are visible at:
https://treeship.dev/verify/[agent-name]
Each subagent has its own verification page showing its complete audit trail.

Best Practices

1. Unique Agent Names

Give each subagent a distinct name for clear audit trails:
  • frontend-dev not dev
  • security-reviewer not reviewer
  • db-migration not migration

2. Tool Restrictions

Only give subagents the tools they need + attestation tools:
{
  "read-only-analyst": {
    tools: ["Read", "Grep", "Glob", "treeship_attest"]
    // No Write, no Bash - can only read and attest
  }
}

3. Verify Before Trust

Always verify handoff attestations before building on previous work:
1. treeship_list_attestations(agent="previous-agent")
2. treeship_verify(attestation_id="...")
3. Check valid: true
4. Then proceed

4. Meaningful Actions

Write attestation actions that explain both what and why:
  • ✅ “Implemented rate limiting to prevent API abuse”
  • ❌ “Added code”

Next Steps