sec-default policy and admission
Overview
mods/sec-default is the built-in organization security default plugin. Its manifest is mods/…/plugin.json; the hook module declared by mods/…/hooks.json is mods/…/register.ts. The module is intended to be seated outermost in the prepend tier and has only three operational moves: continue an event past the user tier with next.to(e, "append"), refuse a user-tier caller or module, or pass the event through unchanged.
Policy is read only from managed settings through $.settings.read({ source: "policy" }), defined in mods/…/source.ts. mods/…/register.ts wraps those reads in Policy.createPolicyMemo(Policy.POLICY_MEMO_MS); mods/…/create-policy-memo.ts shares one in-flight or recent read across a burst, including failures. Boolean guard decisions use mods/…/decided-by-policy.ts, which fails closed by returning true when the policy read or predicate throws.
The register hook protects organization-owned material by routing selected events around the user tier. classic.*, prompt content events, prompt.compose, skill.prompt, attribution.text, session.compact, and all settings.read calls go straight to append in mods/…/register.ts. session.append is held for engine attachment/context rows, compaction rows, Skill tool message rows detected by mods/…/is-skill-row.ts, and note rows from prepend/append plugins. For tool.describe, command.describe, agent.offer, and agent.spawn, mods/…/past-users.ts lets user/builtin/core providers pass normally but sends prepend/append or missing-provider subjects past users.
Admission and refusal behavior is also centered in mods/…/register.ts:
session.identityfrom the user tier is answered with a deny-shaped value from mods/…/identity-refusal.ts; non-user callers go past the user tier.tool.registerlets prepend/append registrations bypass users. For user-tier registrations, mods/…/register-refusal-of.ts denies when managedallowedMcpServersis set, or when the plugin/tool name would read as an organization MCP server or organization plugin tool.tool.listreads policy, gets the organization-side list (next.to(e, "append")), the full-chain list, and the engine/builtin list, then merges them with mods/…/managed-tools-restored.ts. Organization tools keep their organization-listed definitions; user-added tools that would be refused at registration are dropped; organization deny-rule removals are applied by mods/…/org-removals-applied.ts.env.setlets prepend/append writes go past users, but user-tier writes to pinned variables are denied by mods/…/pinned-variable-refusal.ts. Pinned names come from managedenv, managedprocessWrapper, policy/source/sign-in variables, and code-loading variables in mods/…/pinned-names.ts, policy-source-variables.ts, process-wrapper-variable.ts, and code-loading-variables.ts.- ui.log,
env.get, andwasm.compilefrom prepend/append callers go past users so user hooks cannot rewrite organization plugin logs, reads, or wasm compilation.
Held verdicts are implemented in mods/sec-default/hooks/held-verdict/** and used by the tool.check and tool.judge rows in mods/…/register.ts. The first run asks the full chain. mods/…/rewritten-by-users.ts inspects next.trace for user-holding tiers that rewrote a verdict without tightening it. If mods/…/deny-rules-hold.ts says the organization has not set allowModsToOverrideDenyRules: true, the hook reruns past users and returns the held verdict when holds-over.ts or holds-at-judge.ts says a deny/ask/classifier verdict should stand. Notices are emitted once per plugin and held kind through untold-notices.ts and held-notice.ts; catch handlers use caught-answer.ts to return the last vouched verdict or an unchecked deny.
Early-run protection keeps user mods from carrying out the model's or another plugin's unallowed calls. mods/…/create-call-memory.ts remembers up to 256 newest calls per maker from tool.call and agent.call, marks allowed calls at tool.run, notes checks at tool.check, and clears stale entries at the next person prompt. User-tier tool.call, fs.write, process.run, and process.spawn are matched by own-call-match.ts, tool-repeats.ts, write-repeats.ts, and process-repeats.ts; refusal-of.ts denies matching effects unless the policy decision allows mods to override deny rules and, for repeated non-script calls, the rules-only $.tool.check allows them. Settings-file writes or commands that name settings files are detected by is-settings-file.ts and names-settings-file.ts and are denied with the settings-write refusal.
Plugin admission uses the plugin.register row in mods/…/register.ts. The hook records the engine provenance in admittedAs for later tool-registration exemptions. It then reads managed policy and applies two plugin options stored under pluginConfigs.cc-plugin-sec-default@builtin.options, read by mods/sec-default/hooks/policy/own-option/**:
allowManagedModsOnlyis true unless absent or exactlyfalse, per mods/…/is-managed-mods-only.ts. If set and the plugin's scanned moduleusesare non-empty, mods/…/uses-nothing.ts determines it must be constrained. A plugin under a dev-mods folder is refused whole with mods/…/managed-mods-only-refusal.ts; other user-tier plugins continue past users with modules stripped by mods/…/without-modules.ts, so non-module plugin parts can still load.forceHotReloadPromptis true unless absent or exactlyfalse, per mods/…/is-hot-reload-prompt-forced.ts. For plugins under a session dev-mods folder detected by mods/…/dev-mods-folder-of.ts, the hook asks$.ui.askusing strings from hot-reload-prompt.ts. A yes is cached in-memory per folder and persisted in$.storeunderhot-reload-yes:<folder>; a no or no answer refuses the plugin. Theplugin.registercatch handler logs mods/…/admission-failure.ts, then fails closed: preserve a previously allowed yes or a hook that already passed managed-only checks, otherwise refuse dev-mods, pass modules that use nothing, or strip modules.
Organization plugin identity is determined from managed enabledPlugins, prependPlugins, and appendPlugins. mods/…/is-org-plugin.ts compares whole plugin ids with folded ids; mods/sec-default/hooks/policy/managed-tools-restored/is-org-tool/** derives organization MCP server names and organization plugin tool scopes for register/list protections. A managed enabled plugin can keep its own tool name when its engine-recorded id matches, while names only in prepend/append still count as organization names for refusing impostor tools.
Tests live under mods/sec-default/tests/**. tests/register.test.ts is the end-to-end suite for registration, routing, refusals, early-run behavior, hot reload prompting, and admission catches. Focused policy tests cover the policy memo, managed-only option, hot-reload option, deny-rule override option, managed tool restoration, held verdict ranking/notices, and dev-mods folder parsing.
Coverage / routing
This doc owns the mods/sec-default/** area, including:
- mods/…/README.md
- mods/…/plugin.json
mods/sec-default/hooks/**mods/sec-default/tests/**
Route changes here when they affect the sec-default plugin's policy reads, hook registration, admission decisions, managed/pinned/tool/identity refusals, hot-reload prompt flow, held verdicts, early-run call matching, or tests for those behaviors.
Coupling
- If mods/…/register.ts changes which events call
next.to(e, "append"), verify mods/…/hooks.json and mods/…/README.md still describe the same hook surface and organization/user-tier boundary. Several rows are intentionally pass-through-only and comments in register.ts note engine skip optimizations that must be updated in engine tests if the row starts doing more. - If the managed option key or built-in plugin id changes, update mods/…/own-options-path.ts and all option readers (is-managed-mods-only.ts, is-hot-reload-prompt-forced.ts, deny-rules-hold.ts) together; otherwise managed settings will silently read as unset or holding.
- If policy settings add new ways to name MCP servers or managed plugins, update both registration and list restoration paths:
mods/sec-default/hooks/policy/managed-tools-restored/is-org-tool/**, mods/…/reads-as-org-tool.ts, mods/…/names-org-tool.ts, and mods/…/register-refusal-of.ts must agree on name folding and the managed-enabled own-plugin exemption. - If Claude Code adds new variables that redirect policy, sign-in, process wrapping, or child-code loading, update mods/…/policy-source-variables.ts, code-loading-variables.ts, and the pinned-variable tests/fixtures.
env.setfail-closed behavior means missing a name is the dangerous case: user plugins could repoint later managed hooks or policy reads. - If tool verdict shapes or
next.traceentries change, updatemods/sec-default/hooks/held-verdict/verdicts/**and mods/…/held-verdict.test.ts together. The hold logic depends on comparing verdict identity, leniency, plugin/rule/hook/setting fields, and which tiers can hold users. - If new built-in tools can run commands, scripts, or write files, extend mods/…/code-tools.ts, written-path-of.ts, is-script.ts, and matching tests/fixtures. Early-run refusal only catches effects it can map from remembered model calls to user-mod operations.
- If plugin admission input changes, keep mods/…/uses-nothing.ts and mods/…/without-modules.ts in sync with the engine's
plugin.registershape.allowManagedModsOnlydepends on strippedprovides.modulespreventing hooks and$calls while preserving other plugin parts. - If dev-mods folder layout changes, update mods/…/dev-mods-folder-of.ts and mods/…/dev-mods-folder-of.test.ts; persisted yes answers are keyed only by the parsed
dev-mods/<session id>folder string.
Risks
- mods/…/register.ts fails closed on many policy-read failures. A transient
$.settings.read({ source: "policy" })rejection can deny user tool registration, pin everyenv.set, hold verdicts, or strip/refuse modules until mods/…/create-policy-memo.ts expires its memo window. - mods/…/process-repeats.ts, names-settings-file.ts, and is-settings-file.ts are best-effort string/path recognizers. Encoded commands, split commands, aliases, unlisted wrappers, environment handoff, or settings paths built in pieces can avoid early-run refusal and let a user mod perform work that should have waited for permission.
- mods/…/hot-reload-prompt.ts stores approvals in this plugin's
$.storeand asks through$.ui.ask. Anything already able to act as the user or answer UI prompts can influence the approval, and a yes covers later edits in the same parsed dev-mods folder. - mods/…/managed-tools-restored.ts reasons mostly from tool names. If an organization tool or plugin is renamed without updating managed settings name derivation, user-added lookalikes may be treated incorrectly or legitimate organization tools may be dropped from
tool.list.