clawdbot/PR_SUMMARY.md

PR: Agent-specific Sandbox and Tool Configuration

Summary

Adds support for per-agent sandbox and tool configurations in multi-agent setups. This allows running multiple agents with different security profiles (e.g., personal assistant with full access, family bot with read-only restrictions).

Changes

Core Implementation (5 files, +49 LoC)

1. src/config/types.ts (+4 lines)

   • Added sandbox and tools fields to routing.agents[agentId] type

2. src/config/zod-schema.ts (+6 lines)

   • Added Zod validation for routing.agents[].sandbox and routing.agents[].tools

3. src/agents/agent-scope.ts (+12 lines)

   • Extended resolveAgentConfig() to return sandbox and tools fields

4. src/agents/sandbox.ts (+12 lines)

   • Modified defaultSandboxConfig() to accept agentId parameter
   • Added logic to prefer agent-specific sandbox config over global config
   • Updated resolveSandboxContext() and ensureSandboxWorkspaceForSession() to extract and pass agentId

5. src/agents/pi-tools.ts (+15 lines)

   • Added agent-specific tool filtering before sandbox tool filtering
   • Imports resolveAgentConfig and resolveAgentIdFromSessionKey

Tests (3 new test files, 18 tests)

1. src/agents/agent-scope.test.ts (7 tests)

   • Tests for resolveAgentConfig() with sandbox and tools fields

2. src/agents/sandbox-agent-config.test.ts (6 tests)

   • Tests for agent-specific sandbox mode, scope, and workspaceRoot overrides
   • Tests for multiple agents with different sandbox configs

3. src/agents/pi-tools-agent-config.test.ts (5 tests)

   • Tests for agent-specific tool filtering
   • Tests for combined global + agent + sandbox tool policies

Documentation (3 files)

1. docs/multi-agent-sandbox-tools.md (new)

   • Comprehensive guide for per-agent sandbox and tool configuration
   • Examples for common use cases
   • Migration guide from single-agent configs

2. docs/concepts/multi-agent.md (updated)

   • Added section on per-agent sandbox and tool configuration
   • Link to detailed guide

3. docs/gateway/configuration.md (updated)

   • Added documentation for routing.agents[].sandbox and routing.agents[].tools fields

Features

Agent-specific Sandbox Config

{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/clawd",
        "sandbox": { "mode": "off" }
      },
      "family": {
        "workspace": "~/clawd-family",
        "sandbox": {
          "mode": "all",
          "scope": "agent"
        }
      }
    }
  }
}

Result:

• main agent runs on host (no Docker)
• family agent runs in Docker with one container per agent

Agent-specific Tool Restrictions

{
  "routing": {
    "agents": {
      "family": {
        "workspace": "~/clawd-family",
        "tools": {
          "allow": ["read"],
          "deny": ["bash", "write", "edit", "process"]
        }
      }
    }
  }
}

Result:

• family agent can only use the read tool
• All other tools are denied

Configuration Precedence

Sandbox Config

Agent-specific settings override global:

• routing.agents[id].sandbox.mode > agent.sandbox.mode
• routing.agents[id].sandbox.scope > agent.sandbox.scope
• routing.agents[id].sandbox.workspaceRoot > agent.sandbox.workspaceRoot

Note: docker, browser, tools, and prune settings from agent.sandbox remain global.

Tool Filtering

Filtering order (each level can only further restrict):

1. Global tool policy (agent.tools)
2. Agent-specific tool policy (routing.agents[id].tools) ← NEW
3. Sandbox tool policy (agent.sandbox.tools)
4. Subagent tool policy (if applicable)

Backward Compatibility

✅ 100% backward compatible

• All existing configs work unchanged
• New fields (routing.agents[].sandbox, routing.agents[].tools) are optional
• Default behavior: if no agent-specific config exists, use global config
• All 1325 existing tests pass

Testing

New Tests: 18 tests, all passing

✓ src/agents/agent-scope.test.ts (7 tests)
✓ src/agents/sandbox-agent-config.test.ts (6 tests)
✓ src/agents/pi-tools-agent-config.test.ts (5 tests)

Existing Tests: All passing

Test Files  227 passed | 2 skipped (229)
Tests      1325 passed | 2 skipped (1327)

Specifically verified:

• Discord provider tests: ✓ 23 tests
• Telegram provider tests: ✓ 42 tests
• Routing tests: ✓ 7 tests
• Gateway tests: ✓ All passed

Use Cases

Use Case 1: Personal Assistant + Restricted Family Bot

• Personal agent: Host, all tools
• Family agent: Docker, read-only

Use Case 2: Work Agent with Limited Access

• Personal agent: Full access
• Work agent: Docker, no browser/gateway tools

Use Case 3: Public-facing Bot

• Main agent: Trusted, full access
• Public agent: Always sandboxed, minimal tools

Migration Path

Before (global config):

{
  "agent": {
    "sandbox": { "mode": "non-main" }
  }
}

After (per-agent config):

{
  "routing": {
    "agents": {
      "main": { "sandbox": { "mode": "off" } },
      "family": { "sandbox": { "mode": "all", "scope": "agent" } }
    }
  }
}

Related Issues

• Addresses need for per-agent security policies in multi-agent setups
• Complements existing multi-agent routing feature (introduced in 7360abad)
• Prepares for upcoming clawdbot agents CLI (announced 2026-01-07)

Checklist

• Code changes implemented
• Tests written and passing
• Documentation updated
• Backward compatibility verified
• No breaking changes
• TypeScript types updated
• Zod schema validation added