Add managed exceptions for preserved local agent settings

[kelos-bot]

🤖 Kelos Strategist Agent @gjkim42

Area: New Managed-Settings Types & CLI Extensions

Summary

Kanon intentionally preserves destination settings it does not own. That is the right default for co-owned agent files, but it leaves teams without a way to see, justify, or expire local deviations from the central Kanon source.

Today a developer can add a local MCP server, Claude permission block, Codex profile, or other native setting directly to destination state. Kanon may keep applying the shared baseline and still report no rendered drift, because the merge layer preserves those unmanaged entries by design. For individual use that is friendly. For a team-managed source repo it becomes a blind spot:

• Which destination settings are present but not declared in kanon.yaml?
• Which local MCP servers or permission settings are intentionally allowed?
• Which exceptions were temporary and should be removed?
• Can CI or an admin-run rollout fail when unmanaged executable config appears?

Proposal: add a small unmanaged-setting inventory plus a managed exception file, so Kanon can keep preserving co-owned config while making non-source state visible and governable.

Evidence from the current codebase

Kanon already documents and tests this preservation behavior:

• The README says files not rendered by the current source are outside the apply plan; Kanon does not scan, list, delete, or keep destination state for them (README.md:124-128).
• The README also says co-owned config files are merged: Codex config.toml and Claude .claude.json / project .mcp.json preserve other fields and server entries, while Claude settings.json preserves settings outside the rendered hooks section (README.md:190-195).
• MergeRenderedContent dispatches Codex config to mergeTOMLTable, Claude MCP JSON to mergeJSONMapField, and Claude settings to mergeJSONFields (internal/core/merge.go:12-21).
• mergeTOMLTable loads the existing table and only overwrites names present in the desired table, so extra mcp_servers entries remain (internal/core/merge.go:43-54).
• mergeJSONMapField does the same for JSON map fields such as mcpServers (internal/core/merge.go:77-94).
• Tests assert that an unmanaged Codex MCP server named private survives apply (internal/core/apply_test.go:92-131).
• Tests assert that an unmanaged Claude MCP server named private and an unmanaged autoUpdates setting survive apply (internal/core/apply_test.go:368-411).
• Tests also assert that stopped-rendering files are not pruned (internal/core/apply_test.go:64-90).

Net: preservation is not accidental. The missing product layer is not “delete local changes”; it is “make preserved local changes observable and explicitly allowed when teams care.”

Why this matters strategically

This unlocks a new governance use case without weakening individual workflows: teams can centrally manage a baseline while still allowing controlled local additions.

Concrete examples:

1. Local database MCP server: a backend developer needs a local-postgres stdio MCP server for two weeks. Kanon should allow it with an expiry and reason, not hide it forever or force it into the team baseline.
2. Contractor laptop policy: a platform repo manages approved remote MCP servers, but any unmanaged local-command MCP server should fail kanon exceptions check unless it has a named exception.
3. Security incident response: a team wants to ask, “which machines still have unmanaged Claude permissions or extra MCP servers?” without collecting raw prompts or secrets.
4. Shared hosts and service accounts: this composes with destination-home targeting (Add explicit destination-home targeting for shared hosts and service-account runners #95): an admin can scan /home/student01, /home/student02, or a runner account for unmanaged preserved settings before applying the shared source.
5. Gradual adoption: brownfield users can keep local settings while a team migrates them into kanon.yaml, but the local leftovers become visible and time-bounded instead of silent.

External signal

Adjacent config systems generally distinguish owned state from allowed out-of-band state:

• Terraform has ignore_changes for attributes intentionally managed outside Terraform, so ignored drift is declared rather than accidental: https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle
• Kubernetes Server-Side Apply tracks field managers so multiple actors can collaborate on one object without silently overwriting each other’s fields: https://kubernetes.io/docs/reference/using-api/server-side-apply/
• Kyverno has PolicyException resources for explicitly exempting selected resources from selected policy rules: https://kyverno.io/docs/guides/exceptions/

Kanon does not need their complexity. The useful pattern is smaller: when unmanaged state is preserved, the owner should be able to inventory it and optionally require a specific exception record.

Proposed model

Add an optional local exception file under the already-gitignored .kanon/ directory:

# <kanon-home>/.kanon/exceptions.yaml
version: 1
exceptions:
  - id: alice-local-postgres
    selector:
      agent: claude
      scope: user
      kind: mcp_server
      name: local-postgres
    reason: Temporary debugging against local database replica
    owner: alice@example.com
    expires: 2026-07-31

  - id: codex-profile-workbench
    selector:
      agent: codex
      scope: user
      kind: native_field
      path: profiles.workbench
    reason: Local model/provider experiment, not part of shared baseline
    owner: alice@example.com
    expires: 2026-07-15

Keep v1 local and gitignored because these are destination-specific facts. A later source-level policy can add committed allowlists if teams need org-wide exceptions, but the first useful step is machine-local visibility and expiry.

Suggested detected unmanaged kinds for v1:

• mcp_server: extra Codex mcp_servers.* or Claude mcpServers.* entries not selected from kanon.yaml for that target.
• native_field: high-impact native fields Kanon preserves but does not manage, such as Codex profiles.*, Codex top-level provider/model/approval fields, or Claude permissions / autoUpdates.
• skill_directory: destination skill directories that are not rendered by the current source, reported as inventory only at first because stopped-rendering files are currently outside the apply plan.

Each inventory item should include content-free facts only: agent, scope, kind, path/name, destination file, rough risk (executable for local-command MCP, permission for permission fields), and whether a matching exception is present/expired.

CLI proposal

Add a command group that scans destination state against the current source and rendered target selection:

kanon exceptions list
kanon exceptions check --policy warn
kanon exceptions check --policy fail
kanon exceptions add mcp_server claude local-postgres \
  --reason "Temporary local DB debugging" \
  --owner alice@example.com \
  --expires 2026-07-31

Suggested output:

kind         agent   name/path              status      destination
mcp_server   claude  local-postgres         allowed     ~/.claude.json
mcp_server   codex   private-github         untracked   ~/.codex/config.toml
native_field claude  permissions            expired     ~/.claude/settings.json

Suggested behavior:

• exceptions list prints detected unmanaged settings and matching exception status.
• exceptions check --policy warn|fail exits non-zero only in fail mode when unmanaged settings lack a valid exception or have expired exceptions.
• kanon status can later summarize “N unmanaged preserved setting(s), M unapproved” without changing default status semantics in the first slice.
• apply should keep current behavior by default. A later apply --unmanaged-policy fail can reuse the same checker for stricter rollouts.
• Exception matching must be exact enough to avoid blanket bypasses in v1. Prefer agent + scope + kind + name/path; defer glob patterns until real demand exists.

Example team policy

A security-conscious team can add this to its shared repo CI or admin rollout script:

kanon validate
kanon lock check
kanon exceptions check --policy fail
kanon apply --yes

Developers keep the ability to run personal MCP servers or native settings locally, but high-impact deviations are no longer invisible. They either migrate into kanon.yaml, get a local exception with an expiry, or fail the stricter team workflow.

Existing issue overlap check

I reviewed open generated issues and searched all issues for unmanaged/exception/local override overlap before filing. I did not find a focused issue for preserved destination exceptions.

This is distinct from:

• Add setting-level ownership and review metadata for governed agent config #76 setting-level governance metadata: metadata applies to settings already declared in Kanon source. This issue inventories destination settings that are not declared in source.
• Add redacted import surveys for brownfield team adoption #97 redacted import surveys: surveys help brownfield teams discover current settings before adoption. This issue is an ongoing post-adoption guardrail for preserved local deviations.
• Add render manifests and apply provenance for auditable config rollouts #30 render manifests/provenance: manifests describe rendered target state and last-applied source facts. This issue describes extra destination state outside the rendered target contract.
• Add a 'native passthrough' managed-settings type to manage permissions (and other non-portable settings) without a lossy neutral schema #18 native passthrough: passthrough would let Kanon own native fragments. This issue handles native fragments intentionally left outside Kanon ownership.
• Manage context-exclusion patterns for sensitive and noisy files #69 context exclusions and Manage outbound network and web-access policies for agents #70 network/web policies: those define specific managed policy surfaces. This issue gives teams a generic exception ledger for unmanaged destination state.
• Prune orphaned files: 'apply' never removes settings deleted from the spec, silently breaking cross-machine sync #26 pruning: pruning would remove orphaned rendered files. This proposal does not change deletion behavior; it starts with detection and exception status.

It also avoids the excluded lanes: it is not self-development prompt tuning, not documentation/wording polish, and not agent configuration based on PR reviews.

Suggested MVP scope

1. Add destination scanners for known co-owned files: Codex config.toml, Claude .claude.json / project .mcp.json, and Claude settings.json.
2. Compare scanned entries against the current rendered/source-selected settings to identify unmanaged mcp_server, selected high-impact native_field, and optionally skill_directory items.
3. Add .kanon/exceptions.yaml structs, validation, exact selector matching, and expiry parsing.
4. Add kanon exceptions list and kanon exceptions check --policy warn|fail with text and JSON output.
5. Keep outputs content-free: no secret values, no full header values, no instruction/skill bodies.
6. Add tests for extra MCP server detection, matching exceptions, expired exceptions, parse errors in co-owned files, project-scoped paths, and no-output behavior when destination equals source.

Backward compatibility

• Existing kanon.yaml files are unchanged.
• Existing render/diff/apply/update defaults are unchanged.
• .kanon/exceptions.yaml is optional and lives under an already-gitignored directory.
• Preservation remains the default merge behavior.
• Strict enforcement is opt-in through the new check command or a later explicit policy flag.

Non-goals

• Do not delete unmanaged settings in v1.
• Do not collect or upload destination contents.
• Do not create broad glob exceptions in the first implementation.
• Do not turn Kanon into a full endpoint inventory tool; scan only agent settings Kanon already knows how to render or preserve.
• Do not make every individual user maintain exceptions unless they opt into a stricter team workflow.

[kelos-bot]

🤖 Kelos Task Status

Task kanon-triage-issues-ad4519106e23 has succeeded. ✅

[kelos-bot]

🤖 Kelos Agent @gjkim42

Kanon Triage Report

Kind: kind/api
Priority: priority/important-longterm — Valuable governance/control feature for team rollouts, but it is opt-in new surface rather than a current breakage.
Actor: actor/human — The proposal adds new CLI commands/policies and an exceptions file format, so maintainer design review is required before implementation.

Status: STILL VALID

Evidence:

• No merged PRs returned for search 98; recent git log grep for issue number and title keywords had no hits.
• Current merge code still preserves unmanaged co-owned state: MergeRenderedContent routes Codex config, Claude settings, and Claude MCP files through preserving merge helpers, and those helpers overwrite only rendered keys/fields while keeping other entries: https://github.com/kelos-dev/kanon/blob/main/internal/core/merge.go#L12-L23 and https://github.com/kelos-dev/kanon/blob/main/internal/core/merge.go#L27-L94
• Existing tests still assert preservation for stopped-rendering files, unmanaged Codex MCP server/private fields, and unmanaged Claude mcpServers.private/autoUpdates: https://github.com/kelos-dev/kanon/blob/main/internal/core/apply_test.go#L64-L132 and https://github.com/kelos-dev/kanon/blob/main/internal/core/apply_test.go#L368-L411
• CLI registration has no exceptions command group; current commands are init, validate, render, diff, apply, status, lock, ui, import, and update: https://github.com/kelos-dev/kanon/blob/main/internal/cli/root.go#L59-L70
• README still documents that unrendered destination files are not scanned/listed/pruned and co-owned files preserve unmanaged fields: https://github.com/kelos-dev/kanon/blob/main/README.md#L124-L128 and https://github.com/kelos-dev/kanon/blob/main/README.md#L190-L195

Duplicates found: None found

Recommendation: KEEP OPEN — The requested capability is not implemented, still matches documented current behavior, and should stay open for maintainer API review.