service

Paths whose lists accumulate instead of being replaced.

Deny lists must union across layers: replacing a managed deny list with a user one would be a fail-open.

Governs the two table merges — merge_managed_over_user and config_manifest.resolve_scalar. It does not govern the two readers that union name sets rather than TOML tables: model_config.load_mcp_server_trust_lists and mcp_disabled.get_disabled_servers accumulate their own layers directly, including the env tier this set knows nothing about. A third deny list therefore needs an entry here and a decision in those two readers.

Sections whose managed value must be a TOML table.

The manifest also uses STRUCTURED for list-valued settings such as MCP allowlists, so this cannot be derived from OptionKind alone. Parent paths for every manifest option are added dynamically by managed_section_shape_violations below.

("effort",) has no manifest option at all — it is written and read by model_config.load_effort_for_model — so nothing else here would cover it, and a managed scalar would replace the user's whole [effort] table. ("effort", "by_model") needs its own entry for the same reason: a managed scalar there passes the top-level shape check and no manifest option gives the merge validator a type for that path, so it would replace the user's [effort.by_model] table. test_every_managed_table_path_is_enforced pins every entry, because a renamed section would otherwise stop being guarded silently.

Provenance label for a value managed policy decided.

Provenance label for a value the user's own file decided.

Manifest keys whose managed value must never resolve in the user's favor.

Every key here either grants a privilege (approval mode, the YOLO entry in the Shift+Tab cycle, shell auto-approval, the interpreter, its programmatic tool-calling list, and the acknowledgement that exposes every tool to it) or draws a containment boundary (the skill-content allowlist, the recursion limit, the classifier that reviews gated actions, and trace redaction). Ignoring an unusable value for one of these leaves the user's own flag or environment variable in force, which is the escalation the policy meant to forbid, so the launch stops instead.

sandboxes.default is enforced for its value, not as a containment boundary. It names which backend a bare --sandbox selects; it does not decide whether to sandbox, so a launch that asks for no sandbox still runs on the host. Enforcement here rejects a value that cannot be applied, and _apply_managed_sandbox prints a notice when a launch bypasses the named backend, so the gap is visible rather than assumed away.

startup.mode and startup.yolo_switcher must both be listed. Pinning the approval mode while leaving the YOLO entry unenforced keeps unrestricted mode one keypress away in the same file.

Keys that cannot grant privilege keep the ordinary ignore-and-fall-through rule. test_every_enforced_managed_key_resolves_to_a_manifest_option pins each entry to a manifest option, because managed_policy_violations skips a key it cannot resolve, so a rename would turn enforcement into a silent no-op.

Return the fixed managed-config path for the current operating system.

For display and error messages. Anything that decides whether policy is enforceable wants resolve_managed_path.

Return the fixed managed-config path and whether it is authoritative.

What the snapshot loader reads. Callers that report health need this rather than managed_config_path, so a guessed path is never mistaken for an authoritative one.

Return UNION_PATHS rebased onto a subtree rooted at prefix.

merge_toml_tables matches paths relative to where it starts. A merge of one option's own subtree therefore never matches an absolute deny-list path. Passing UNION_PATHS to such a merge does nothing at all. The merge then replaces a nested deny list instead of unioning it, which is a fail-open.

Return whether managed policy decided a value with this source label.

A structured option merges both layers and reports a combined label, so source == MANAGED_SOURCE is the wrong test and silently answers False for a leaf managed policy does control.

Merge managed policy over user config with this project's precedence.

The single statement of managed-over-user precedence. It was assembled by hand at three call sites, two carrying "must match" comments, and had already drifted once: the site that omitted the validator reported a user table as effective while its provenance credited managed policy.

Return whether a managed scalar has the declared type for its path.

Unknown and structured paths retain the deep-merger's existing behavior; their dedicated readers own validation. Manifest-backed scalar leaves are validated before they displace a lower-precedence value.

Classify what managed policy says at one manifest path.

Return managed settings whose declaration cannot be safely applied.

A key is a violation when an enforced managed policy declaration cannot be applied, or when a known managed section has a non-table value. The shape cases matter because "wrong shape" is not "absent": merging such a value can erase a user subtree before a reader falls back to a default.

Required rather than defaulted to the process snapshot: managed_health pairs this with the health of the same snapshot, and a default that silently read the cache is what let a refreshed status be reported next to stale violations.

Resolve one manifest option and retain its rank-keyed managed result.

Return manifest keys managed policy declares whose value was dropped.

Not a launch failure: only ENFORCED_MANAGED_KEYS stops a launch, and every other rejected managed value deliberately falls through to the user tier. But the fall-through was announced only through logger.warning, which the package's in-memory log handler makes unreachable from stderr — the handler installed at import time means logging.lastResort never fires. An administrator who typed max_tokens = "8000" saw a clean green table and had no way to learn the value was ignored.

Return known managed sections declared as non-table values.

Unknown leaf keys remain forward compatible. Every parent path of a manifest-backed option is known to be a table, however, as are the structured options that specifically represent tables. Rejecting a scalar at one of those paths prevents it from replacing an entire user section.

Return the process snapshot, or an isolated snapshot for an explicit path.

A reload that cannot parse the file never evicts policy that parsed cleanly earlier. An unusable snapshot carries data == {}, which every reader would otherwise treat as "nothing is enforced", so caching it would turn one broken write by an administrator into a process-wide fail-open. The caller still receives the failed load, so health checks see the error.

The same holds for a file that parses but cannot be enforced. Its health is OK, so a usability check alone would cache it. When the refresh raises ManagedPolicyError (as require_healthy_managed_config does), the rejected candidate must not stay in the cache: the reload keeps the previous settings, but a later non-refresh reader would otherwise observe the rejected snapshot and, for example, re-enable a managed MCP deny the edit removed. Validate enforceability before caching, so the cache holds only the last enforceable snapshot.

Load one user snapshot and the current managed snapshot.

Managed policy is included exactly when user_path is None, which is what every production caller passes. Reading an explicit path is a test-and-tooling operation on one file, and its result must not be mistaken for the effective configuration.

Deliberately not a caller-supplied flag: an include_managed=False source is indistinguishable from a machine with no policy installed, because the fabricated status reports MISSING and the table is empty. Deriving it here keeps that state one keyword out of reach.

Drop the cached managed snapshot.

Test-only. Production reloads pass refresh=True instead, which keeps the last snapshot that parsed cleanly if the new one fails; clearing the cache first would leave readers with an empty managed table on a failed reload.

Fail startup when present managed policy cannot be parsed or enforced.

A file that parses is not necessarily enforceable: a privilege-affecting key can carry a value the manifest rejects, or a known section can be a scalar instead of a table. Both can otherwise resolve in the user's favor or erase a user subtree, so they stop the launch here rather than at each consumer.

Return managed provider health for diagnostics and config inspection.

Return both halves of exit 78 for one managed snapshot.

Reading health and violations as two calls is a live bug, not a style choice. get_managed_snapshot declines to cache a candidate it cannot enforce, so a refreshed status describes the file on disk while a second, non-refreshed violation read still sees the last enforceable snapshot and reports none. Every diagnostic surface then shows ok for the exact file that just refused to launch. One snapshot, both answers.

Evaluate provider health and policy diagnostics for one snapshot.

Provider that parses one local TOML file per load call.

Managed and user TOML snapshots from one resolution generation.

Raised when an enforced managed source cannot be read safely.

Raised when managed policy declares a value that cannot be enforced.

The file parses, so provider health is OK; the policy it states is what cannot be applied. A subclass of ManagedConfigError so every caller that already fails closed on an unreadable file fails closed here too.

Provider health and policy enforceability from one managed snapshot.