Claude Code Governance Lockdown — Bluefly Agent Platform¶

Core Insight¶

Claude Code enforcement is NOT markdown. It is: managed settings + plugin-only customization + sandbox + hooks + MCP Tool Search + tool-restricted subagents + policyHelper.

CLAUDE.md is guidance. Settings/hooks/policies are enforcement.

Priority Build Packets¶

P0: Managed Policy Baseline¶

managed-settings.json with deny/ask/allow permission tiers
Sandbox with filesystem + network boundaries
strictPluginOnlyCustomization + allowManagedPermissionRulesOnly

P1: Bluefly Claude Plugin¶

Skills: gascity-work-authority, drupal-ddev-validation, openclaw-gateway-operations, closeout-contract
Agents: bluefly-build-operator, drupal-validator, gas-town-release-gatekeeper
Hooks: gascity-session-start, bead-required-pretooluse, protected-path-pretooluse, config-change-auditor

P2: Gas City Policy Helper¶

/usr/local/bin/bluefly-claude-policy — computes managed settings from Oracle Gas City authority
Inputs: cwd, git remote, repo trust class, active bead, user identity, machine role

P3: Context Budget Profile¶

Implements Claude Code context window together with llms.txt v2 and AGENTS.md. See documentation-governance-standard.md §6 for the repository file contract.

ENABLE_TOOL_SEARCH=auto:5
MCP alwaysLoad audit
Path-scoped .claude/rules/ (load on matching file reads; they do not survive /compact unless unscoped)
CLAUDE.md is the Claude Code auto-load surface: thin pointer to AGENTS.md, hard cap 200 lines (context window). Prefer a pointer plus only the rules that must survive compaction. Do not paste catalogs. Operating law lives in AGENTS.md.

P4: Delivery Pressure Hooks¶

PostToolBatch drift detector
SessionEnd closeout reporter
ConfigChange auditor

Highest-Leverage Settings¶

1. Managed Settings (real lock, not CLAUDE.md)¶

Location: - macOS: /Library/Application Support/ClaudeCode/managed-settings.json - Linux/Oracle: /etc/claude-code/managed-settings.json

Managed settings outrank everything — command-line overrides, user settings, project settings.

2. strictPluginOnlyCustomization¶

Blocks skills, agents, hooks, MCP servers from user/project sources. Only plugin or managed sources allowed.

{
  "strictPluginOnlyCustomization": ["skills", "agents", "hooks", "mcp"],
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "blueflyio/claude-code-plugins"
    }
  ]
}

Requires Claude Code v2.1.82+.

3. allowManagedPermissionRulesOnly¶

Blocks user/project settings from defining allow/ask/deny. Only managed rules apply.

{
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true
}

4. policyHelper — Dynamic Policy from Gas City¶

Admin-deployed executable that computes managed settings at startup. Claude Code only honors it from managed locations.

{
  "policyHelper": {
    "path": "/usr/local/bin/bluefly-claude-policy"
  }
}

If it exits nonzero, Claude refuses to start.

5. Sandbox (real file/network boundary)¶

Permission deny rules do NOT cover arbitrary subprocesses. Sandbox does.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws", "~/.config/op", "//**/.env", "//**/.env.*"],
      "denyWrite": ["/", "~", "./UPstreams-DO-NOT-HACK", "./vendor", "./node_modules", "./.git"]
    },
    "network": {
      "allowedDomains": ["gitlab.com", "*.gitlab.com", "packagist.org", "*.drupal.org", "registry.npmjs.org"],
      "deniedDomains": ["api.openai.com"]
    }
  }
}

6. Hooks (deterministic gates, not advice)¶

Four hooks only: - SessionStart: inject Gas City authority state + active bead - UserPromptSubmit: classify packet type + required authority - PreToolUse: block forbidden mutations deterministically - PostToolBatch: detect drift, broad edits, unexpected staged files

7. MCP Tool Search (token saver)¶

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5"
  }
}

Only tool names load at session start. Schemas load when needed.

8. Tool-Restricted Subagents¶

agents:
  drupal-builder:
    tools: [Read, Glob, Grep, Edit, Write, Bash]
    model: sonnet
  policy-reviewer:
    tools: [Read, Glob, Grep]
    model: fable
  release-gatekeeper:
    tools: [Read, Glob, Grep, Bash]
    model: sonnet
  docs-curator:
    tools: [Read, Glob, Grep, Edit]
    model: haiku

9. Thin Main Thread Pattern¶

The hidden gem: Don't optimize the giant session. Stop creating giant sessions.

Main thread = operator/control only. Subagents = disposable heavy work. Focused compaction after every gate.

Main thread holds ONLY:
- current packet
- active Oracle bead
- branch
- approval gates
- next action
- blockers

Subagents handle:
- large file inspection
- broad grep
- upstream research
- test log triage
- diff review
- return limit: 40 lines

Complete Managed Settings Baseline¶

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "minimumVersion": "2.1.173",
  "autoUpdatesChannel": "stable",
  "strictPluginOnlyCustomization": ["skills", "agents", "hooks", "mcp"],
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "blueflyio/claude-code-plugins"
    }
  ],
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "allowManagedMcpServersOnly": true,
  "permissions": {
    "defaultMode": "dontAsk",
    "disableBypassPermissionsMode": "disable",
    "disableAutoMode": "disable",
    "deny": [
      "Edit(**/UPstreams-DO-NOT-HACK/**)",
      "Write(**/UPstreams-DO-NOT-HACK/**)",
      "NotebookEdit(**/UPstreams-DO-NOT-HACK/**)",
      "Read(//**/.env)",
      "Read(//**/.env.*)",
      "Read(//**/secrets/**)",
      "Bash(*doctor --fix*)",
      "Bash(*--dangerously-skip-permissions*)",
      "Bash(*rm_rf_governed*)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(glab mr merge *)",
      "Bash(*systemctl restart*)",
      "Bash(*openclaw gateway restart*)",
      "Bash(*dolt sql*)",
      "Bash(*drush cex*)"
    ],
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git fetch*)",
      "Bash(npm test*)",
      "Bash(npm run lint*)",
      "Bash(npm run typecheck*)",
      "Bash(composer validate*)",
      "Bash(ddev describe*)"
    ]
  },
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws", "~/.config/op", "//**/.env", "//**/.env.*", "//**/secrets/**"],
      "denyWrite": ["/", "~", "./UPstreams-DO-NOT-HACK", "./vendor", "./node_modules", "./.git"]
    },
    "network": {
      "allowedDomains": ["gitlab.com", "*.gitlab.com", "packagist.org", "*.drupal.org", "registry.npmjs.org", "*.npmjs.org"],
      "deniedDomains": ["api.openai.com"],
      "allowLocalBinding": true
    }
  },
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5",
    "OTEL_LOG_TOOL_DETAILS": "0",
    "OTEL_LOG_TOOL_CONTENT": "0",
    "OTEL_LOG_RAW_API_BODIES": "0"
  },
  "cleanupPeriodDays": 7
}

Repo CLAUDE.md (Target: <10 lines)¶

# Bluefly Runtime Contract
Oracle Gas City is work authority.
Mac is workstation only.
DDEV is validation only.
Drupal is implementation/presentation target.
UPstreams-DO-NOT-HACK is read-only reference.
Procedures live in skills. Enforcement lives in managed settings/hooks.

Token Discipline Lock (paste into agent instructions)¶

Main thread is operator/control only. Do not load large files, full logs, broad grep output, or upstream docs into the main context.
Use disposable subagents for heavy discovery and return only: conclusion, exact files/line ranges, commands run, validation evidence, next action.
Keep MCP Tool Search enabled with ENABLE_TOOL_SEARCH=auto:5. Do not always-load large MCP servers.
After every major gate, run focused compaction: keep only packet, Oracle bead, branch, files changed, tests, approval gates, blockers, and next command.
Reports over 40 lines are failures unless explicitly requested.