← 23.423.6 →
2500 words No Slides

Video 23.5: Enterprise Multi-Agent Patterns

Course: Claude Code - Parallel Agent Development (Course 4) Section: 23: Orchestration and Best Practices Video Length: 4–5 minutes Presenter: Daniel Treasure

Opening Hook

When you move multi-agent development into the enterprise, everything changes. You can't just spin up agents and hope for the best. You need security, audit trails, human oversight, compliance tracking, and role-based permissions. Today, we're building an enterprise-grade multi-agent framework that keeps agents powerful while keeping your organization safe.

Key Talking Points

What to say:

Security: Minimum Permissions Per Agent - Principle of least privilege: each agent gets exactly the permissions they need, no more. - Example: Auth agent gets read/write access to src/auth/ directory, but not src/database/. Database agent vice versa. - File-level permissions: Agents can't even see files outside their scope. - Environment variable scoping: Secrets (API keys, database credentials) are per-agent. Auth agent doesn't see database credentials.

Human Oversight: Hooks as Enforcement Gates - TeammateIdle and TaskCompleted hooks aren't just quality gates; they're governance gates. - Hooks can enforce: "Before going idle, pass linting. Before marking done, pass tests AND get human code review." - The human review part is key: a hook can block completion and require a human to review the code before the agent proceeds. - This is how you prevent agents from doing something problematic.

CI/CD Integration: Automated Quality - Enterprise teams can't afford bad code. CI/CD pipelines enforce standards: - Linting (code style). - Testing (correctness). - Security scanning (vulnerable dependencies, secrets in code). - Coverage checks (test coverage > 80%). - Performance tests (didn't we slow down?). - Hooks trigger the CI/CD pipeline. If pipeline fails, task is rejected.

Compliance: Audit Logging for Agent Actions - Every agent action is logged: what file they edited, when, what changed, why. - Logs are immutable (stored securely, not modifiable by agents). - Used for compliance audits ("Show me what Agent_3 did to the payment module"). - Useful for incident response: "This vulnerability was introduced by Agent_1 in task XYZ on date D. What happened?"

Role-Based Agent Permissions - Different agents have different roles: Backend, Frontend, QA, DevOps, Security. - Permissions tied to roles: - Backend agent: Read/write src/backend/, can run tests. - DevOps agent: Read/write infrastructure/, can execute deployments (carefully gated). - Security agent: Read all, write security configs, can scan for vulnerabilities. - Roles simplify permission management and reduce the chance of over-privileging agents.

Team Configuration as Code - Team definitions (which agents, what permissions, which hooks) are stored as code (JSON or YAML). - Checked into version control (it's team policy). - Changes are reviewed and approved before deployment. - Makes governance auditable and consistent.

What to show on screen:

  1. File-based permission model
  2. Show a directory tree with permission annotations.

  3. Highlight which agents can read/write which files.

  4. Hooks enforcing human review

  5. Show a hook script that blocks completion and requires human review.

  6. Show the workflow: task done → hook checks → if code risky, require human approval → human approves → task completes.

  7. CI/CD pipeline integration

  8. Show a GitHub Actions workflow or similar.

  9. Highlight the security scan step, coverage check, and test step.

  10. Audit log example

  11. Show logs of agent actions with timestamps, file changes, and reasoning.

  12. Team configuration file

  13. Show a settings.json with role-based permissions.

  14. Compliance dashboard (conceptual)

  15. Show a dashboard tracking: code coverage, test pass rate, security issues found/fixed, audit log entries.

Demo Plan

Scenario: You're setting up a multi-agent team for a fintech startup (payment processing). Security and compliance are critical. You'll configure the team with role-based permissions, hooks, and audit logging.

Timing: ~4 minutes

Step 1: Define Roles and Permissions (45 seconds)

  • Show the team configuration file. Start with roles: json { "team": { "name": "payment-platform", "roles": { "backend_engineer": { "permissions": [ "src/payment/**:rw", "src/auth/**:rw", "src/database/**:r", "tests/backend/**:rw", "execute:unit_tests", "execute:integration_tests" ] }, "security_engineer": { "permissions": [ "src/**:r", "config/**:rw", "security/policy.yaml:rw", "execute:security_scan", "execute:dependency_check" ] }, "devops_engineer": { "permissions": [ "infrastructure/**:rw", "deployment/**:rw", "config/secrets.yaml:r", "execute:deploy_staging", "execute:deploy_production_approval_needed" ] } } } }

  • Explain: "Each role has specific permissions. Backend engineers can modify payment code but only read database code. Security engineers can scan everything. DevOps needs approval to deploy to production."

Step 2: Assign Agents to Roles (30 seconds)

  • Add the agents section: json "agents": [ { "name": "payment_agent", "role": "backend_engineer", "model": "claude-sonnet", "budget": 25 }, { "name": "security_agent", "role": "security_engineer", "model": "claude-opus", "budget": 15 }, { "name": "devops_agent", "role": "devops_engineer", "model": "claude-haiku", "budget": 10 } ]

  • Explain: "Payment agent is a backend engineer. Security agent is security-focused (needs Opus for threat analysis). DevOps agent is Haiku because deployments are scripted."

Step 3: Add Hooks with Human Oversight (60 seconds)

  • Add hooks section: json "hooks": { "taskCompleted": ".claude/hooks/enterprise-gate.sh", "teamateIdle": ".claude/hooks/lint-and-review.sh" }

  • Show the enterprise gate script: ```bash #!/bin/bash # .claude/hooks/enterprise-gate.sh # Gate for production-critical code

input=$(cat) task_subject=$(echo "$input" | jq -r '.task_subject') teammate=$(echo "$input" | jq -r '.teammate_name') cwd=$(echo "$input" | jq -r '.cwd')

cd "$cwd"

# Step 1: Run tests if ! pytest -v --tb=short; then echo "✗ Tests failed. Fix and resubmit." >&2 exit 2 fi

# Step 2: Security scan (if payment code modified) if git diff HEAD -- src/payment/ | grep -q .; then echo "Payment code modified. Running security scan..." >&2 if ! ./scripts/security-scan.sh; then echo "✗ Security scan failed. Review before approval." >&2 exit 2 fi fi

# Step 3: Human review for critical files if git diff HEAD -- src/payment/stripe_handler.py | grep -q .; then echo "REQUIRES HUMAN REVIEW: Changes to stripe_handler.py detected." >&2 echo "Submit for code review at: https://code-review.company.com/tasks/$task_id" >&2 echo "Once approved, task can be marked complete." >&2 exit 2 # Block until human reviews fi

echo "✓ All checks passed. Task approved." >&2 exit 0 ```

  • Explain: "This hook checks tests, security scans, and requires human review for payment-critical code. Agent can't bypass it."

Step 4: Enable Audit Logging (45 seconds)

  • Show the audit configuration: json "audit": { "enabled": true, "log_path": ".claude/audit.log", "log_fields": [ "timestamp", "agent_name", "task_id", "action", "files_modified", "git_commit", "exit_code" ] }

  • Show sample audit log output: 2025-02-13T14:23:45.123Z | payment_agent | task-001 | TASK_START | src/payment/payment.py | - | 0 2025-02-13T14:24:12.456Z | payment_agent | task-001 | FILE_EDIT | src/payment/payment.py | +45 lines, -12 lines | 0 2025-02-13T14:24:30.789Z | payment_agent | task-001 | TEST_RUN | tests/test_payment.py | 127/127 passed | 0 2025-02-13T14:24:50.012Z | payment_agent | task-001 | HOOK_GATE | enterprise-gate.sh | Security scan | 0 2025-02-13T14:25:15.345Z | payment_agent | task-001 | HUMAN_REVIEW_REQUIRED | stripe_handler.py | Waiting for approval | 2 2025-02-13T15:10:22.678Z | security_audit | - | HUMAN_APPROVAL | task-001 | Code reviewed and approved | 0 2025-02-13T15:10:30.901Z | payment_agent | task-001 | TASK_COMPLETE | src/payment/payment.py | Commit abc123def | 0

  • Explain: "Every action is logged. If something goes wrong, we can trace what happened, by whom, and when."

Step 5: Show Compliance Dashboard (45 seconds)

  • Describe (or show a mockup): ``` COMPLIANCE DASHBOARD: payment-platform ───────────────────────────────────────── Period: Last 30 days

SECURITY METRICS: ✓ Test coverage: 89% (target: 80%) ✓ Security scans: 100% of payment code scanned ✓ Vulnerabilities found: 2 (both fixed) ✓ Failed lint checks: 0 (blocked by hooks)

AUDIT TRAIL: ✓ Total agent tasks: 247 ✓ Human reviews required: 12 (all approved) ✓ Tasks blocked by hooks: 18 (agents fixed and resubmitted) ✓ Audit logs stored: 8,392 entries (immutable)

COMPLIANCE SIGN-OFF: ✓ SOC 2 requirements: All met ✓ PCI-DSS (payment compliance): All met ✓ Last audit: 2025-02-13 (PASSED)

ALERTS: ⚠ One agent (devops_agent) accessed production secrets 5 times Review: Approved (deployment tasks) ```

  • Explain: "This dashboard proves your compliance. Security team can show auditors that agents are controlled, monitored, and gated."

Step 6: Show Permission Enforcement in Action (45 seconds)

  • Simulate an attack:
  • Payment agent tries to edit src/database/migrations.py (outside their permission scope).
  • System blocks: "Permission denied: payment_agent cannot write to src/database/migrations.py"
  • Log entry created (someone tried to access what they shouldn't).

  • Security team is alerted.

  • Explain: "Even if an agent goes rogue or is compromised, they can't access resources outside their scope. Permissions are enforced at the file system level."

Code Examples & Commands

Example 1: Enterprise Team Configuration

{
  "team": {
    "name": "fintech-payment-platform",
    "environment": "production",

    "roles": {
      "backend_engineer": {
        "description": "Develops backend services",
        "permissions": [
          {
            "resource": "src/payment/**",
            "access": "rw",
            "conditions": ["tests_pass", "security_scan_pass"]
          },
          {
            "resource": "src/auth/**",
            "access": "rw",
            "conditions": ["tests_pass"]
          },
          {
            "resource": "src/database/**",
            "access": "r"
          },
          {
            "resource": "tests/**",
            "access": "rw"
          },
          {
            "resource": "execute:unit_tests",
            "access": "x"
          },
          {
            "resource": "execute:integration_tests",
            "access": "x"
          }
        ]
      },

      "security_engineer": {
        "description": "Conducts security reviews and scanning",
        "permissions": [
          {
            "resource": "src/**",
            "access": "r"
          },
          {
            "resource": "config/**",
            "access": "rw"
          },
          {
            "resource": "security/**",
            "access": "rw"
          },
          {
            "resource": "execute:security_scan",
            "access": "x"
          },
          {
            "resource": "execute:dependency_check",
            "access": "x"
          },
          {
            "resource": "execute:sast_analysis",
            "access": "x"
          }
        ]
      },

      "devops_engineer": {
        "description": "Manages infrastructure and deployments",
        "permissions": [
          {
            "resource": "infrastructure/**",
            "access": "rw"
          },
          {
            "resource": "deployment/**",
            "access": "rw"
          },
          {
            "resource": "config/secrets.yaml",
            "access": "r",
            "constraints": ["audit_logged", "approval_required"]
          },
          {
            "resource": "execute:deploy_staging",
            "access": "x"
          },
          {
            "resource": "execute:deploy_production",
            "access": "x",
            "constraints": ["human_approval_required"]
          }
        ]
      }
    },

    "agents": [
      {
        "name": "payment_backend_agent",
        "role": "backend_engineer",
        "model": "claude-sonnet",
        "max_budget_usd": 25,
        "capabilities": ["coding", "testing"],
        "restrictions": []
      },
      {
        "name": "security_compliance_agent",
        "role": "security_engineer",
        "model": "claude-opus",
        "max_budget_usd": 15,
        "capabilities": ["security_analysis", "compliance_review"],
        "restrictions": ["cannot_deploy", "cannot_modify_application_code"]
      },
      {
        "name": "devops_infrastructure_agent",
        "role": "devops_engineer",
        "model": "claude-haiku",
        "max_budget_usd": 10,
        "capabilities": ["infrastructure", "deployment"],
        "restrictions": ["requires_human_approval_for_production"]
      }
    ],

    "hooks": {
      "taskCompleted": ".claude/hooks/enterprise-quality-gate.sh",
      "taskCompleted_payment": {
        "path": ".claude/hooks/payment-critical-gate.sh",
        "applies_to": ["src/payment/**"],
        "description": "Extra security for payment-critical code"
      },
      "teamateIdle": ".claude/hooks/lint-and-format.sh"
    },

    "audit": {
      "enabled": true,
      "immutable_log_path": "/var/log/claude-code-audit/team.log",
      "log_level": "debug",
      "retention_days": 365,
      "fields": [
        "timestamp",
        "agent_name",
        "task_id",
        "action_type",
        "resource",
        "old_value",
        "new_value",
        "git_commit",
        "status",
        "error_message"
      ]
    },

    "compliance": {
      "standards": ["SOC2", "PCI-DSS", "ISO27001"],
      "annual_audit_required": true,
      "code_review_required_for": ["src/payment/**", "config/secrets.yaml"],
      "human_sign_off_required_for": ["deployment_production"],
      "security_scan_required_for": ["src/payment/**", "src/auth/**"]
    }
  }
}

Example 2: Permission Enforcement Hook

#!/bin/bash
# .claude/hooks/permission-check.sh
# Enforce file-level permissions before allowing edits

input=$(cat)
teammate=$(echo "$input" | jq -r '.teammate_name')
cwd=$(echo "$input" | jq -r '.cwd')

cd "$cwd"

# Load permissions config
permissions=$(jq ".team.roles[] | select(.name == \"${teammate}\") | .permissions[]" config/permissions.json)

# Get list of files modified in this task
modified_files=$(git diff --name-only HEAD)

echo "Permission Check for $teammate" >&2

for file in $modified_files; do
  # Check if teammate has permission to modify this file
  allowed=$(echo "$permissions" | grep "$file" | grep "w" | wc -l)

  if [ "$allowed" -eq 0 ]; then
    echo "✗ PERMISSION DENIED: $teammate cannot modify $file" >&2
    echo "  This action has been logged for compliance review." >&2
    exit 2
  fi
done

echo "✓ All file modifications are within scope." >&2
exit 0

Example 3: Human Review Requirement Hook

#!/bin/bash
# .claude/hooks/human-review-gate.sh
# Require human code review for critical code

input=$(cat)
task_id=$(echo "$input" | jq -r '.task_id')
teammate=$(echo "$input" | jq -r '.teammate_name')
cwd=$(echo "$input" | jq -r '.cwd')

cd "$cwd"

# Check if critical files were modified
critical_files=("src/payment/" "src/auth/" "config/")

review_required=0
for pattern in "${critical_files[@]}"; do
  if git diff HEAD -- "$pattern" | grep -q .; then
    review_required=1
    break
  fi
done

if [ $review_required -eq 1 ]; then
  echo "HUMAN CODE REVIEW REQUIRED" >&2
  echo "Task: $task_id by $teammate" >&2
  echo "Review URL: https://code-review.company.com/tasks/$task_id" >&2
  echo "Approver: Email @security-team to approve and comment 'APPROVED'" >&2
  exit 2
fi

echo "✓ No critical files modified. Human review not required." >&2
exit 0

Example 4: Audit Logging

#!/bin/bash
# .claude/hooks/audit-log.sh
# Log all agent actions for compliance

input=$(cat)
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%S.000Z")
agent=$(echo "$input" | jq -r '.teammate_name')
task_id=$(echo "$input" | jq -r '.task_id')
cwd=$(echo "$input" | jq -r '.cwd')

cd "$cwd"

# Get git diff summary
files_changed=$(git diff HEAD --name-only | wc -l)
lines_added=$(git diff HEAD --numstat | awk '{sum+=$1} END {print sum}')
lines_removed=$(git diff HEAD --numstat | awk '{sum+=$2} END {print sum}')

# Create audit entry
audit_entry="{
  \"timestamp\": \"$timestamp\",
  \"agent\": \"$agent\",
  \"task_id\": \"$task_id\",
  \"action\": \"TASK_COMPLETED\",
  \"files_changed\": $files_changed,
  \"lines_added\": $lines_added,
  \"lines_removed\": $lines_removed,
  \"git_commit\": \"$(git rev-parse HEAD)\",
  \"status\": \"success\"
}"

# Append to immutable audit log
echo "$audit_entry" >> /var/log/claude-code-audit/team.log

echo "Audit logged: $task_id" >&2
exit 0

Gotchas & Tips

Gotcha 1: Over-Permission - You give agents "read all" to simplify setup. Now a compromised agent can see all your secrets. - Tip: Always use least privilege. If an agent doesn't need to read it, block access.

Gotcha 2: Audit Log Not Immutable - Audit logs are stored in a regular file. Agent (or attacker) modifies the log to hide their tracks. - Tip: Store audit logs on a separate, read-only system. Use write-once storage (like AWS S3 Object Lock).

Gotcha 3: Human Review is Bottleneck - Every task requires human review. Now you have 16 agents blocked waiting for one human. - Tip: Only require human review for critical paths. Use hooks to auto-approve low-risk changes.

Gotcha 4: Role Definitions Drift - You define roles in code once, then manually grant permissions to new agents. Soon they diverge. - Tip: Make role definitions the source of truth. Every agent gets permissions based on their role, not one-offs.

Gotcha 5: Secrets in Audit Logs - Audit logs capture everything, including if an agent accessed a secret. Now the log itself is sensitive. - Tip: Hash secrets in logs (don't log the value, log "secret_accessed:payment_api_key"). Or exclude secrets from audit.

Lead-out

You've now built a production-ready, enterprise-grade multi-agent team: secure, compliant, auditable, and human-overseen. But what if you want to automate the orchestration itself? What if you need agents coordinating other agents, or building custom UIs for team management? That's where the Claude Code SDK comes in. Next video, we're going programmatic.

Reference URLs

  • Principle of Least Privilege: https://en.wikipedia.org/wiki/Principle_of_least_privilege
  • SOC 2 Compliance: https://www.aicpa.org/soc-2
  • PCI-DSS (Payment Card Security): https://www.pcisecuritystandards.org/
  • Role-Based Access Control (RBAC): https://en.wikipedia.org/wiki/Role-based_access_control
  • AWS S3 Object Lock (immutable logs): https://docs.aws.amazon.com/AmazonS3/latest/userguide/ObjectLock.html

Prep Reading

  1. Enterprise security frameworks: NIST Cybersecurity Framework, ISO 27001.
  2. Compliance standards relevant to your industry: PCI-DSS for payments, HIPAA for healthcare, etc.
  3. Audit logging best practices: Log aggregation, immutability, retention.
  4. Code review workflows: How humans integrate into automated pipelines.

Notes for Daniel

This video is about trust and control. Enterprises deploy agents when they believe agents can be trusted. Your job is to show that trust is built on transparency, enforcement, and oversight.

Walk through the JSON configuration as policy. Say things like, "This says payment_agent can write to payment code, but not database code. This is policy, not just setup." Make it concrete.

The audit log is powerful. Show it as a compliance artifact. "If an auditor asks, 'What did your agents do to that critical file?', you can answer with logs."

Emphasize that even with automation, humans are in the loop for critical decisions. The hooks don't replace human judgment; they enforce it.

If your audience is technical, they'll appreciate the depth. If it's business/compliance focused, simplify to: security, auditability, control.