Implement per-agent environment isolation per docs/per-agent-environment-design.md

[orveth]

Summary

Implements the per-agent environment isolation contract from
docs/per-agent-environment-design.md
(the spec branch / PR #12 as the design contract).

PR #11 already landed the runtime scaffolding (per-agent state dir,
tmux wrapper, systemd service, --effort max). This PR layers the
declarative library + per-agent whitelist + new exec recipe on top.

What landed (6 steps)

1. Library option families — three new modules, each declaring its
   option schema only:

   • modules/skills.nix — services.forge.skills.<name> = { source; description; }
   • modules/mcp-servers.nix — services.forge.mcpServers.<name> = { command; args; env; }
   • modules/plugins.nix — services.forge.plugins.<name> = { source; }

   All three are imported from modules/default.nix.

2. Library installation in modules/harnesses/claude-code.nix:

   • skills -> /etc/forge/skill-library/<name>/ via environment.etc
   • plugins -> /etc/forge/plugin-library/<name>/ via environment.etc
   • MCP servers don't need an install path (transcribed into the per-agent .mcp.json).
   • Defensive uniqueness assertions for each family.

3. Per-agent whitelist + permissions schema on services.forge.agents.<name>
   (extends modules/agents.nix):

   • skills, mcpServers, plugins, allowedTools (each listOf str, default [])
   • permissions = { allow = []; deny = []; skipPrompts = true; }
     (schema only — skipPrompts reserved for the scoped-permissions follow-up)
   • Cross-cutting assertions: every name referenced from an agent must
     resolve in the corresponding library family.

4. Per-agent CWD assembly on every wrapper start:

   • CLAUDE.md (role text — already from PR Add claude-code harness runtime — agents into running processes #11)
   • .claude/skills/<name> symlinks per declared skill (wiped + recreated each start)
   • .claude/settings.json generated from permissions.{allow,deny}
   • .claude/skill-catalog.md generated from skills' descriptions (always written)
   • .mcp.json generated from declared MCP servers (always written, even {"mcpServers":{}})
   • .env (discord token plumbing — kept intact from PR Add claude-code harness runtime — agents into running processes #11)

5. New exec recipe per the spec's "The exec recipe" section:

   • --bare intentionally dropped (would break OAuth subscription auth)
   • --strict-mcp-config intentionally dropped (would strip plugin-bundled MCPs)
   • --mcp-config .mcp.json
   • --plugin-dir /etc/forge/plugin-library/<name> per declared plugin
   • --settings .claude/settings.json + --setting-sources project
   • --append-system-prompt-file .claude/skill-catalog.md
   • --dangerously-skip-permissions
   • --allowedTools "<joined>" only when non-empty (empty would strip built-in tools)
   • Old hasDiscord + --channels "plugin:discord@..." line removed; discord
     flows through services.forge.plugins.discord in v2.

6. Demo agent migrated in deployments/agicash-team-forge/configuration.nix:
   the example block now declares the shared library (skills / mcpServers /
   plugins) plus the agent's whitelist + allowedTools, per the spec example
   shape. Kept fully commented-out until the operator runs the sops bootstrap.

Deferred (named in the spec's Non-goals)

• nix develop .#agent.<name> devShell output (step 7 from spec) — defer
• disallowedTools beyond schema — defer
• Per-agent Linux user — defer (current design has agents on same runAs)
• Plugin/comms split (services.forge.comms.<name>) — defer
• Hooks family (PreToolUse / PostToolUse) — defer
• Library namespacing — defer (single-host single-team for now)
• harness portability fields — defer

Validation

Run before opening this PR:

• nix flake check passes (with a placeholder deploy-config.nix)
• nix eval --raw .#nixosConfigurations.agicash-team-forge.config.system.build.toplevel.drvPath
  resolves to a valid system derivation
• Eval test instantiating a config with a declared skill / plugin / MCP
  server confirms environment.etc."forge/skill-library/<name>".source
  and .../plugin-library/<name>".source resolve to store paths
• Generated wrapper script passes bash -n for both the
  full-whitelist case and the empty-whitelist (no skills / mcps / plugins
  / allowedTools) case
• Negative test: misspelled skill name in an agent triggers the
  services.forge.agents.<name>.skills references "<typo>" but ... is not declared in services.forge.skills assertion with the
  expected message

Test plan

• Operator does the sops bootstrap (docs/secrets-bootstrap.md) and
  uncomments the demo block in
  deployments/agicash-team-forge/configuration.nix
• deploy-rs rolls out the change; systemctl status forge-agent-coordinator
  reports active
• Attach via sudo -u gudnuf tmux -L forge attach -t agent-coordinator
  and exercise the spec's validation criteria (skill isolation, MCP
  isolation, plugin MCPs load, no user-level skill/MCP/settings leak)

🤖 Generated with Claude Code