Config Inheritance

SCC computes one effective configuration before it launches an agent. The merge order is:

organization defaults -> selected team profile -> project .scc.yaml

The selected team comes from scc team switch, scc start --team, or the current setup profile. The project layer is the repository or worktree that SCC is launched from; v1 does not have a separate project registry.

Configuration Inheritance Flow

Merge Rules

Setting	Org	Team	Project	Effective behavior
Providers	Sets allowed providers	Can choose within org policy	No provider selection in .scc.yaml	Launch fails closed if the selected provider is not allowed
Plugins	Defines defaults, allowlist, and blocks	Adds delegated plugins	Adds delegated plugins	Allowed additions accumulate; org security blocks always win
MCP servers	Defines allowlist, stdio policy, and blocks	Adds delegated MCP servers	Adds delegated MCP servers	Allowed additions accumulate; blocked, disallowed, or policy-incompatible servers are omitted
network_policy	Sets baseline	Can keep or tighten	Can keep or tighten	Looser values are ignored and reported under “Ignored Policy Changes”
dev_environment.commands	Defines named commands	Adds named commands when allow_dev_environment_commands matches the team	Adds named commands when project overrides and team command delegation are enabled	Accepted command names accumulate; duplicate names are ignored and reported under “Ignored Policy Changes”; execution requires scc dev run <name>
dev_environment.logs	Defines named log actions	Adds named log actions when allow_dev_environment_commands matches the team	Adds named log actions when project overrides and team command delegation are enabled	Same fixed-argv and duplicate-name rules as commands; execution requires scc dev logs <name>
dev_environment.health_checks	Defines named health checks	Adds named health checks when allow_dev_environment_commands matches the team	Adds named health checks when project overrides and team command delegation are enabled	Same fixed-argv and duplicate-name rules as commands; execution requires scc dev health <name>
Session settings	Sets defaults	Overrides defaults	Overrides team values	Last accepted value wins; session.auto_resume is advisory in v1

Caution

Do not use .scc.yaml to select teams or loosen organization policy. Project config is for project-specific additions and stricter local posture.

Plugins

Plugins are additive. For example:

Org default:  safety-net
Team adds:    java-tools
Project adds: repo-linter
Effective:    safety-net, java-tools, repo-linter

An addition is omitted when it matches security.blocked_plugins, does not match defaults.allowed_plugins, or is requested from a layer that lacks delegation.

Use:

scc config explain --field plugins
scc config explain --field blocked
scc config explain --field denied

to see which plugins were accepted, blocked, or denied.

MCP Servers

MCP servers are also additive, but every server must pass the same governance checks before it reaches the effective config:

• org security.blocked_mcp_servers;
• org defaults.allowed_mcp_servers, when configured;
• team or project delegation rules;
• stdio MCP policy, when type: stdio;
• the effective network_policy.

When the effective network_policy is locked-down-web, network MCP servers (http or sse) are blocked because the runtime has no external network.

Use unique MCP server names. Provider renderers project the accepted effective MCP server list into provider-native config, and duplicate native keys can only have one final provider value.

Network Policy

network_policy values have this restrictiveness order:

open < web-egress-enforced < locked-down-web

Teams and projects can keep the inherited value or move right in that order. They cannot move left.

Example:

Org default:  locked-down-web
Team asks:    open
Project asks: web-egress-enforced
Effective:    locked-down-web

The team and project attempts are ignored because both would loosen the inherited policy. SCC records those attempts in the explain output:

scc config explain --field network
scc config explain --json

Look for Ignored Policy Changes in text output or ignored_policy_changes in JSON output.

Dev Environment Bridge Actions

dev_environment.commands, dev_environment.logs, and dev_environment.health_checks are named bridge-action contracts for projects that already use a devcontainer or Docker Compose stack. Each action must use a fixed argv list. SCC does not accept shell strings here.

Organization defaults can define baseline commands:

{
  "defaults": {
    "dev_environment": {
      "commands": {
        "test": {
          "argv": ["uv", "run", "pytest", "-q"],
          "working_directory": ".",
          "timeout_seconds": 120,
          "description": "Run the project test suite"
        }
      },
      "logs": {
        "api": {
          "argv": ["docker", "compose", "logs", "--tail", "100", "api"],
          "timeout_seconds": 30,
          "description": "Read recent API logs"
        }
      },
      "health_checks": {
        "api": {
          "argv": ["curl", "-fsS", "http://localhost:8000/health"],
          "timeout_seconds": 10,
          "description": "Check local API health"
        }
      }
    }
  }
}

Teams can add commands only when the org delegates that capability:

{
  "delegation": {
    "teams": {
      "allow_dev_environment_commands": ["casework"]
    }
  }
}

Projects can add commands, logs, and health checks only when project overrides are enabled for the team and the team is allowed by allow_dev_environment_commands. Accepted action names accumulate within each section. A team or project cannot override an already accepted name in the same section; SCC reports the duplicate under “Ignored Policy Changes”.

Inspect the effective contract with:

scc config explain --field dev_environment
scc config explain --json

Run one accepted command with:

scc dev run test .
scc dev logs api .
scc dev health api .
scc dev status . --json
scc dev run test . --json

Execution is fail-closed around audit: SCC writes a pre-execution audit event before starting the host process. If that audit write fails, the action does not run. The host process receives only the fixed argv list with shell=false; working_directory is resolved inside the workspace after symlink resolution. Output is returned as bounded stdout/stderr tails and is not written to durable audit metadata. scc dev status --json is read-only and reports the effective bridge contract without executing a host process.

Session Settings

Session settings use last accepted value wins:

Org default timeout:  12 hours
Team timeout:         8 hours
Project timeout:      4 hours
Effective timeout:    4 hours

session.auto_resume is accepted and shown in explain output, but it is advisory in v1. SCC’s actual quick-resume behavior is tied to the active work context: selected team, repository/worktree path, branch, and provider.

Work Context

SCC v1 treats the current repository or worktree as project identity. The work context includes:

• selected team;
• repository root;
• worktree path and branch;
• provider ID (claude or codex);
• last session/container identity.

This keeps switching simple:

scc team switch platform
cd ~/repos/payments-api
scc start --provider codex

scc team switch support
cd ~/repos/case-system
scc start --provider claude

Each provider gets separate session identity, so a Claude session and a Codex session in the same repository do not overwrite each other.

Minimal Example

Organization config:

org-config.json

{
  "schema_version": "1.0.0",
  "organization": { "name": "Example Municipality", "id": "example-muni" },
  "defaults": {
    "allowed_providers": ["claude", "codex"],
    "allowed_plugins": ["scc-safety-net", "internal-*"],
    "allowed_mcp_servers": ["*.example.gov"],
    "network_policy": "web-egress-enforced",
    "dev_environment": {
      "commands": {
        "test": {
          "argv": ["uv", "run", "pytest", "-q"],
          "working_directory": ".",
          "timeout_seconds": 120
        }
      }
    }
  },
  "security": {
    "blocked_plugins": ["shadow-*"],
    "blocked_mcp_servers": ["*.personal.example"]
  },
  "delegation": {
    "teams": {
      "allow_additional_plugins": ["internal-*"],
      "allow_additional_mcp_servers": ["casework"],
      "allow_dev_environment_commands": ["casework"]
    },
    "projects": { "inherit_team_delegation": true }
  },
  "profiles": {
    "casework": {
      "allowed_plugins": ["scc-safety-net"],
      "additional_plugins": ["internal-case-helper"],
      "additional_mcp_servers": [
        {
          "name": "casework",
          "type": "sse",
          "url": "https://casework.example.gov/mcp"
        }
      ],
      "delegation": { "allow_project_overrides": true }
    }
  }
}

Project config:

.scc.yaml

additional_plugins:
  - internal-repo-linter

additional_mcp_servers:
  - name: project-docs
    type: sse
    url: https://docs.example.gov/mcp

network_policy: locked-down-web

session:
  timeout_hours: 4

Because the project tightens from web-egress-enforced to locked-down-web, network MCP servers are blocked in the final effective config. SCC reports that through Blocked Items.

Commands

scc team switch casework
scc config validate
scc config explain
scc config explain --json
scc config explain --field network
scc config explain --field blocked
scc config explain --field denied

For source-backed claim ownership, see Docs Claim Map.