# Claude Code Web Simulation Environment

Comprehensive simulation of Claude Code Web's agent execution engine, MCP server integration, sandbox isolation, and ggen deterministic pipeline orchestration.

## Research Findings: Claude Code Web Capabilities

### ✅ Docker Container Support
Claude Code Web **CAN** launch Docker containers through:
- Official devcontainer setup with VSCode Dev Containers
- Docker Sandbox integration template
- `--dangerously-skip-permissions` mode for unattended agent operation
- Pre-configured Docker solutions with multi-layer security

**Sources:**
- [Development containers - Claude Code Docs](https://code.claude.com/docs/en/devcontainer)
- [Configure Claude Code | Docker Docs](https://docs.docker.com/ai/sandboxes/claude-code/)
- [Docker Blog: Run Claude Code locally Docker Model Runner](https://www.docker.com/blog/run-claude-code-locally-docker-model-runner/)

### 🔐 Sandbox & Network Security
Claude Code Web implements strict OS-level isolation:
- Network access restricted to proxy server (domain whitelisting)
- Linux bubblewrap / MacOS seatbelt for OS-level enforcement
- All child processes inherit security boundaries
- User confirmation for new domain requests
- Custom proxy support for advanced rules

**Key Security Note:** Docker socket access (`/var/run/docker.sock`) could bypass sandbox - controlled by configuration.

**Sources:**
- [Sandboxing - Claude Code Docs](https://code.claude.com/docs/en/sandboxing)
- [Anthropic Engineering: Claude Code Sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing)
- [Sandbox Runtime - GitHub](https://github.com/anthropic-experimental/sandbox-runtime)

### 🔌 MCP Server Integration
Claude Code Web connects to 200+ pre-built MCP servers:
- Configuration in `~/.claude.json` (user scope) or `.mcp.json` (project scope)
- Tool search feature for large tool sets
- Environment variable configuration (MCP_TIMEOUT, MAX_MCP_OUTPUT_TOKENS)
- Proxy server support for tool access

**Sources:**
- [Connect Claude Code to tools via MCP - Claude Code Docs](https://code.claude.com/docs/en/mcp)
- [MCPcat: Best MCP Servers for Claude Code](https://mcpcat.io/guides/best-mcp-servers-for-claude-code/)
- [Docker Blog: Add MCP Servers to Claude Code](https://www.docker.com/blog/add-mcp-servers-to-claude-code-with-mcp-toolkit/)

## Simulation Architecture

```
claude-code-web-simulator/
├── README.md                    # This file
├── main.sh                      # Main orchestrator
├── config/
│   ├── environment.json         # Sandbox configuration
│   ├── mcp-servers.json         # MCP server definitions
│   └── security-policy.json     # Network/security rules
├── modules/
│   ├── sandbox-simulator.sh     # Sandbox isolation
│   ├── mcp-proxy.sh             # MCP server proxy
│   ├── hooks-engine.sh          # SessionStart/post-task hooks
│   ├── agent-orchestrator.sh    # Multi-agent coordination
│   ├── ggen-pipeline.sh         # μ₁-μ₅ stages
│   ├── receipt-generator.sh     # Deterministic receipts
│   ├── invocation-patterns.sh   # Agent patterns
│   ├── error-handler.sh         # Exit codes and errors
│   └── memory-integrator.sh     # Agent memory system
├── examples/
│   ├── simple-validation.sh     # Example 1: Spec validation
│   ├── multi-agent-gen.sh       # Example 2: Multi-agent generation
│   ├── watch-mode.sh            # Example 3: Watch mode
│   └── error-recovery.sh        # Example 4: Error handling
├── workspace/                   # Simulation work directory
│   ├── agent-memory/            # Agent memory storage
│   ├── sandboxes/               # Per-agent sandbox dirs
│   ├── receipts/                # Deterministic receipts
│   └── audit-logs/              # Audit trails
└── test/                        # Test suite
    ├── test-sandbox.sh
    ├── test-mcp-proxy.sh
    ├── test-multi-agent.sh
    └── test-determinism.sh
```

## Key Features

### 1. Sandbox Isolation
- Per-agent isolated workspace (like `GGEN_HOME` per agent)
- Network access restricted to whitelisted domains
- No direct filesystem access to host
- Exit code enforcement

### 2. Multi-Agent Orchestration
- Parallel agent execution with dependency management
- Agent lifecycle: bootstrap → initialize → execute → cleanup
- Agent memory sharing via JSON metadata
- Collision detection for overlapping operations

### 3. ggen Pipeline Simulation
Full simulation of μ₁-μ₅ deterministic pipeline:
- **μ₁ Normalize**: RDF validation, SHACL shapes, dependency resolution
- **μ₂ Extract**: SPARQL queries, OWL inference, rule execution
- **μ₃ Emit**: Tera template rendering, code generation
- **μ₄ Canonicalize**: Deterministic formatting, content hashing
- **μ₅ Receipt**: Cryptographic proof, audit trail

### 4. Deterministic Receipts
- SHA-256 content hashing for reproducibility verification
- Execution timestamps (ISO 8601)
- Manifest + ontology fingerprinting
- File-by-file change tracking
- Full audit trail with timing data

### 5. Agent Invocation Patterns
- **Pattern A**: Validation (pre-flight checks, dry-run)
- **Pattern B**: JSON Output (for machine parsing and orchestration)
- **Pattern C**: Watch Mode (continuous regeneration on file changes)
- **Pattern D**: Dry-Run (preview changes without committing)

### 6. Error Handling
Exit codes for automation:
- `0`: Success
- `1`: General error
- `2`: Validation failed (SHACL, schema errors)
- `4`: SPARQL error (query syntax, inference failure)
- `5`: Template error (Tera rendering failure)
- `126`: Permission denied
- `127`: Command not found
- `130`: Interrupted (Ctrl+C)

### 7. MCP Server Integration
- Proxy for tool access through sandbox boundaries
- Tool search and resolution
- Environment variable forwarding
- Timeout management

### 8. Hook System
- **SessionStart**: Bootstrap agent environment, install ggen, setup MCP servers
- **post-tool**: Update agent memory after operations
- **post-edit**: Validate changes, update audit trail
- **pre-task**: Validate inputs before execution
- **convergence**: Synthesize parallel agent outputs

## Usage

### Start the Simulation Environment
```bash
./main.sh start
```

### Run a Single Agent (Validation)
```bash
./main.sh run-agent validation --spec myspec.ttl --dry-run
```

### Run Multi-Agent Workflow
```bash
./main.sh run-workflow multi-gen --ontology ont.ttl --templates *.tera --parallel 4
```

### Monitor Simulation
```bash
./main.sh monitor
```

### Stop Simulation
```bash
./main.sh stop
```

### View Receipts and Audit Trails
```bash
./main.sh view-receipts
./main.sh view-audit-trail
```

## Examples

### Example 1: Simple Specification Validation
```bash
./examples/simple-validation.sh
# Shows: Single agent validating RDF spec against SHACL shapes
# Output: Deterministic receipt with validation status
```

### Example 2: Multi-Agent Code Generation
```bash
./examples/multi-agent-gen.sh
# Shows: 4 parallel agents (RDF, Template, Validation, Verification)
# Output: Generated code + collision detection + convergence
```

### Example 3: Watch Mode
```bash
./examples/watch-mode.sh
# Shows: Continuous regeneration on ontology changes
# Output: Streaming receipts with file change detection
```

### Example 4: Error Recovery
```bash
./examples/error-recovery.sh
# Shows: Agent error handling and automatic retry logic
# Output: Exit codes, error messages, recovery procedures
```

## Testing

Run the comprehensive test suite:
```bash
./test/test-sandbox.sh           # Sandbox isolation
./test/test-mcp-proxy.sh         # MCP server proxy
./test/test-multi-agent.sh       # Multi-agent coordination
./test/test-determinism.sh       # Deterministic receipt verification
```

## Architecture Details

### Sandbox Simulator
Each agent runs in an isolated sandbox:
- Unique workspace directory
- Separate environment variables
- Network proxy with domain restrictions
- No access to host filesystem outside workspace
- Exit code propagation

### MCP Proxy
Forwards tool requests from agents to MCP servers:
- Domain whitelist enforcement
- Tool lookup and resolution
- Timeout management
- Response formatting

### Hook Engine
Executes hooks at critical points:
- SessionStart: Initialize sandbox, install dependencies
- pre-task: Validate inputs
- post-tool: Update memory
- convergence: Synthesize outputs

### Agent Orchestrator
Manages multi-agent workflows:
- Dependency graph construction
- Parallel execution scheduling
- Collision detection
- Memory synchronization
- Cleanup and shutdown

### ggen Pipeline
Full simulation of μ₁-μ₅ deterministic transformation:
- Stage-by-stage execution
- Determinism verification
- Performance timing
- Error tracking

### Receipt Generator
Produces cryptographic proofs of execution:
- SHA-256 hashing
- Timestamp recording
- Manifest fingerprinting
- Audit trail composition

### Agent Memory Integrator
Shared memory system for agents:
- JSON metadata storage
- Generation event tracking
- Cross-agent context
- Collision detection data

## Performance Characteristics

- **Agent bootstrap**: ~2-3s (ggen installation, MCP setup)
- **ggen sync (μ₁-μ₅)**: <5s (1k+ triples, simulated)
- **Multi-agent parallel execution**: 1.3-1.5x sequential time for 4 agents
- **Receipt generation**: <100ms (SHA-256 hashing)
- **Memory persistence**: <50ms (JSON serialization)

## Security Considerations

1. **Sandbox Isolation**: Each agent's workspace is isolated from others and host
2. **Network Restrictions**: Only whitelisted domains accessible
3. **Exit Code Enforcement**: Failures propagate and stop dependent workflows
4. **Memory Isolation**: Agent memory stored in sandboxed workspace only
5. **Docker Integration**: Docker socket access controlled by security policy

## Extensibility

Add new agent types:
1. Create agent script in `modules/agents/`
2. Register in `agent-orchestrator.sh`
3. Define memory schema in `config/memory-schema.json`
4. Add error codes to `error-handler.sh`

Add new MCP servers:
1. Define in `config/mcp-servers.json`
2. Update proxy in `mcp-proxy.sh`
3. Test with `test/test-mcp-proxy.sh`

## License

MIT - Part of ggen v26.5.19

## See Also

- ggen documentation: `/home/user/ggen/docs/`
- CLAUDE.md: `/home/user/ggen/CLAUDE.md`
- Claude Code Web Agent Integration: `/home/user/ggen/docs/installation/CLAUDE_CODE_WEB_GUIDE.md`
