Skip to content

Capability Allowlist (A1/A2) ​

This guide documents the release behavior of capability governance.

1. Files and Merge Model ​

Allowlist policy is always composed from two layers:

  1. packaged default: crates/cccc-daemon/resources/capability-allowlist.default.yaml
  2. user overlay: CCCC_HOME/config/capability-allowlist.user.yaml

Effective policy is deterministic merge:

  • effective = merge(default, overlay)
  • mapping keys are merged recursively
  • non-mapping values (including lists) are replaced by overlay value

No env/path override compatibility remains. Use overlay APIs only.

2. Policy Levels ​

Supported level values:

  1. indexed: kept in local catalog, hidden from normal discovery/exposure
  2. mounted: searchable/discoverable, can be enabled on demand
  3. enabled: mounted + preferred baseline intent (does not auto-mutate runtime state by itself)
  4. pinned: enabled + long-lived baseline intent (typically applied via actor-profile/role defaults)

Runtime mutation still happens only through explicit enable flows (capability_enable / capability_use) or actor profile default application on actor start.

Release baseline policy:

  1. third-party sources are discoverable by default (mounted)
  2. external capability sources default to usable path (mounted) in normal mode
  3. conservative users can switch external capability sources back to indexed through external_capability_safety_mode
  4. runtime flow has no approval gate; enable path is one-step when enable_supported=true
  5. blocked is explicit deny state (policy/source/runtime blocklist), reserved for clear deny signals

Runtime blocklist model:

  1. scope=group: foreman or user can block/unblock capabilities for this group
  2. scope=global: only user can block/unblock capabilities globally
  3. block action immediately revokes bindings and runtime tool visibility (relist/reconnect required)

3. Runtime Discovery Model ​

Search uses the built-in capabilities and locally stored catalog records, including records imported explicitly or retained from an earlier installation. It does not query remote registries or run a periodic source sync. Source identifiers in existing records describe their origin; they do not imply that automatic search of that source is available.

Unimported results saved from the retired SkillsMP remote search are left out of search, because their name and content may not match. They are not deleted: existing bindings keep working, they can still be used by ID, and the Capability Center and the member and profile pickers list them as Unverified old search result. To rely on one, find a trusted original source and import it with a supported method; when that source is gone, the skill may not be recoverable. An explicit import records where it came from; it does not verify the content.

A user or agent can still explicitly install a supported local path, URL, or GitHub target, subject to the applicable policy. Explicit remote installation may use the network; it is separate from catalog search.

4. Daemon Ops (Global Overlay) ​

Use these IPC ops for allowlist governance:

  1. capability_allowlist_get
  2. capability_allowlist_validate
  3. capability_allowlist_update
  4. capability_allowlist_reset

Update/reset require by="user".

capability_allowlist_update supports optimistic concurrency via expected_revision.

5. Web API Endpoints ​

Web routes map to daemon ops:

  1. GET /api/v1/capabilities/allowlist
  2. POST /api/v1/capabilities/allowlist/validate
  3. PUT /api/v1/capabilities/allowlist
  4. DELETE /api/v1/capabilities/allowlist

6. External Capability Safety Mode ​

capability_allowlist_get / validate / update expose external_capability_safety_mode as a thin semantic view over the default posture for external capability sources:

  1. normal => external capability sources default to mounted
  2. conservative => external capability sources default to indexed

Built-in packs are unaffected. Per-source and per-capability overrides can still be stricter.

  1. call capability_allowlist_get
  2. inspect external_capability_safety_mode and current revision
  3. prepare patch (or full replacement)
  4. call capability_allowlist_validate
  5. apply with capability_allowlist_update(expected_revision=...)
  6. if mismatch, refetch and retry

Use capability_allowlist_reset to drop overlay and return to packaged default.

Released under the Apache-2.0 License.