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:
- packaged default:
crates/cccc-daemon/resources/capability-allowlist.default.yaml - 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:
indexed: kept in local catalog, hidden from normal discovery/exposuremounted: searchable/discoverable, can be enabled on demandenabled: mounted + preferred baseline intent (does not auto-mutate runtime state by itself)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:
- third-party sources are discoverable by default (
mounted) - external capability sources default to usable path (
mounted) in normal mode - conservative users can switch external capability sources back to
indexedthroughexternal_capability_safety_mode - runtime flow has no approval gate; enable path is one-step when
enable_supported=true blockedis explicit deny state (policy/source/runtime blocklist), reserved for clear deny signals
Runtime blocklist model:
scope=group: foreman or user can block/unblock capabilities for this groupscope=global: only user can block/unblock capabilities globally- 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:
capability_allowlist_getcapability_allowlist_validatecapability_allowlist_updatecapability_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:
GET /api/v1/capabilities/allowlistPOST /api/v1/capabilities/allowlist/validatePUT /api/v1/capabilities/allowlistDELETE /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:
normal=> external capability sources default tomountedconservative=> external capability sources default toindexed
Built-in packs are unaffected. Per-source and per-capability overrides can still be stricter.
7. Recommended Workflow
- call
capability_allowlist_get - inspect
external_capability_safety_modeand current revision - prepare patch (or full replacement)
- call
capability_allowlist_validate - apply with
capability_allowlist_update(expected_revision=...) - if mismatch, refetch and retry
Use capability_allowlist_reset to drop overlay and return to packaged default.