Context

brood-box currently injects credentials, git config, and MCP config into the guest VM, but not the user's global agent settings — rules, skills, agents/personas, commands, instructions, and configuration files. Without these, the coding agent inside the VM starts with a "blank slate," missing the user's customizations that make it productive.

The goal is a declarative, per-agent settings injection framework that copies host settings into the guest rootfs before boot. It must follow strict DDD, be easy to maintain, and support future agents with minimal code changes.

Feature Matrix: What Each Agent Needs

Claude Code (~/.claude/ + ~/.claude.json)

Codex CLI (~/.codex/ + ~/.agents/)

OpenCode (~/.config/opencode/ + Claude Code compat paths)

OpenCode lives at github.com/anomalyco/opencode. It has built-in Claude Code compatibility: it reads ~/.claude/CLAUDE.md as an instructions fallback, searches ~/.claude/skills/ for skills, and also searches .agents/skills/ (shared with Codex). These are controllable via OPENCODE_DISABLE_CLAUDE_CODE, OPENCODE_DISABLE_CLAUDE_CODE_SKILLS, and OPENCODE_DISABLE_EXTERNAL_SKILLS.

Deferred: Claude Code Memory

~/.claude/projects/<encoded-path>/memory/ uses path encoding based on the host workspace path. Inside the VM, the workspace is at /workspace, so the encoded path differs. Remapping requires understanding Claude Code's undocumented encoding scheme. Defer to a follow-up.

Implementation Plan

Phase 1: Domain Types — pkg/domain/settings/

New file: pkg/domain/settings/settings.go

Pure value objects and interface. Zero I/O.

// EntryKind classifies how a settings entry is injected.
type EntryKind int
const (
    KindFile      EntryKind = iota // Copy single file
    KindDirectory                   // Recursive directory copy
    KindMergeFile                   // Parse, filter fields, merge into existing guest file
)

// FieldFilter defines an allowlist of top-level keys to extract from a config file.
// Only keys in AllowKeys are copied. Security: denylist would leak new sensitive keys.
type FieldFilter struct {
    AllowKeys   []string            // Top-level keys to include (empty = copy all)
    DenySubKeys map[string][]string // Sub-keys to strip within allowed keys (e.g. "providers": ["*.apiKey"])
}

// Entry describes a single item to inject from host to guest.
type Entry struct {
    Category string    // "settings", "instructions", "rules", "agents", "skills", "commands", "tools", "plugins", "themes"
    HostPath string    // Relative to $HOME on host
    GuestPath string   // Relative to guest home (usually same as HostPath)
    Kind     EntryKind
    Optional bool      // Skip silently if source missing (true for all settings entries)
    Filter   *FieldFilter // Only for KindMergeFile
    Format   string       // Only for KindMergeFile: "json", "toml", "jsonc"
}

// Manifest is the per-agent list of settings to inject.
type Manifest struct {
    Entries []Entry
}

// Safety limits (mirrors credential package pattern)
const (
    MaxFileSize  int64 = 1 << 20  // 1 MiB per file
    MaxTotalSize int64 = 50 << 20 // 50 MiB aggregate
    MaxFileCount       = 500
    MaxDepth           = 8
)

// Injector copies filtered settings from the host into the guest rootfs.
type Injector interface {
    Inject(rootfsPath, hostHomeDir string, manifest Manifest) error
}

New file: pkg/domain/settings/filter.go — Pure FilterEntries function for category filtering.

Phase 2: Extend Existing Domain Types

• pkg/domain/agent/agent.go — Add SettingsManifest *settings.Manifest field to Agent struct
• pkg/domain/vm/vm.go — Add SettingsManifest *settings.Manifest to VMConfig
• pkg/domain/config/config.go — Add SettingsImportConfig and SettingsCategoryConfig types with IsCategoryEnabled(). Add to Config and AgentOverride structs. Merge rules: workspace-local .broodbox.yaml can only disable (tighten-only), same as Auth and MCP.Authz.

Phase 3: Infrastructure — Settings Injector

New package: internal/infra/settings/

FSInjector implements settings.Injector. Pattern mirrors internal/infra/credential/store.go.

Behavior per EntryKind:

• KindFile: Copy file, validate size, 0600 perms, chown 1000:1000, skip symlinks
• KindDirectory: Recursive copy with safety limits (MaxDepth, MaxFileCount, MaxFileSize, MaxTotalSize), skip symlinks, path containment checks
• KindMergeFile: Parse (JSON/TOML/JSONC), apply allowlist filter, strip deny sub-keys, deep-merge into existing guest file, write back

Also: stripJSONC() helper for OpenCode's JSONC format, and comprehensive table-driven tests.

Phase 4: Rootfs Hook

New file: internal/infra/vm/settingshook.go — InjectSettings hook factory following InjectCredentials pattern.

Phase 5: Fix MCP Deep-Merge (Critical Prerequisite)

Modify: internal/infra/vm/mcpconfig.go

Current mergeJSONKey replaces the entire value for a top-level key. When settings injection writes user's MCP servers into mcpServers in .claude.json, the MCP hook would overwrite them all with just sandbox-tools.

Fix: deep-merge into the mcpServers/mcp_servers/mcp maps instead of replacing. Add deepMergeJSONMapKey helper.

Phase 6: Hook Ordering in VM Runner

Modify: internal/infra/vm/runner.go

Insert InjectSettings between credentials and MCP:

1. SSH keys + init binary + env file + git config
2. InjectCredentials
3. InjectSettings (NEW)
4. InjectMCPConfig

Add settingsInjector settings.Injector field and WithSettingsInjector option to MicroVMRunner.

Phase 7: Agent Registry Manifests

Modify: internal/infra/agent/registry.go

Populate SettingsManifest for each built-in agent with the entries from the feature matrix above. This is the key data declaration — adding a future agent only requires declaring its manifest entries here.

Note on OpenCode: The OpenCode manifest includes Claude Code compatibility paths (~/.claude/CLAUDE.md, ~/.claude/skills/) alongside native OpenCode paths. These are all Optional: true, so if the user doesn't have Claude Code installed, the entries are silently skipped.

Phase 8: Application Layer Pass-Through

Modify: pkg/sandbox/sandbox.go — Add resolveSettingsManifest method (follows resolveMCPConfig pattern), filter entries by enabled categories, pass to VMConfig.

Phase 9: Composition Root Wiring

Modify: cmd/bbox/main.go — Wire FSInjector, add --no-settings CLI flag, config handling.
Modify: pkg/runtime/factory.go — Wire default settings injector.

Config Schema

# ~/.config/broodbox/config.yaml
settings_import:
  enabled: true          # Default: true. --no-settings overrides.
  categories:
    settings: true       # Config files (settings.json, config.toml, etc.)
    instructions: true   # CLAUDE.md, AGENTS.md
    rules: true          # rules/*.md (Claude Code)
    agents: true         # Agent persona files
    skills: true         # Skills directories
    commands: true       # Slash command files
    tools: true          # Custom tools (OpenCode)
    plugins: true        # Plugins (OpenCode)
    themes: true         # Themes (OpenCode)

# Per-agent override:
agents:
  claude-code:
    settings_import:
      categories:
        skills: false    # Disable skills for Claude Code only

Security Considerations

1. Allowlist for MergeFile fields — Only explicitly listed top-level keys are copied. New unknown keys in agent config updates are safely ignored. Prevents credential leakage from evolving config formats.
2. Tighten-only from workspace config — .broodbox.yaml can only disable settings import, not enable it. Prevents malicious repos from enabling injection to exfiltrate host data.
3. Filter specs are non-configurable — AllowKeys and DenySubKeys are hardcoded in the agent manifest. A workspace cannot modify what gets stripped.
4. Size limits — 1 MiB per file, 50 MiB aggregate, 500 files max, 8 levels depth.
5. Symlink rejection — os.Lstat + skip symlinks to prevent reading arbitrary host files.
6. Path containment — All paths validated to stay under rootfs sandbox home, reusing containedPath pattern.
7. File permissions — All injected files written with 0600, chown to 1000:1000.

Files Summary

Adding a New Agent in the Future

To add a new coding agent, a developer only needs to:

1. Add the agent to internal/infra/agent/registry.go (already required)
2. Populate its SettingsManifest with the appropriate Entry items
3. No new code paths needed — the framework handles all injection

This is the same pattern as CredentialPaths and MCPConfigFormat — declarative data on the agent value object, with generic infrastructure that operates on it.