Introducing a new way to review your PRs.

Read the announcement

anthropics / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

View on GitHub

13 documents · Updated Nov 16, 2026

docs / sec-default-policy-and-admission

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.identity from the user tier is answered with a deny-shaped value from mods/…/identity-refusal.ts; non-user callers go past the user tier.
  • tool.register lets prepend/append registrations bypass users. For user-tier registrations, mods/…/register-refusal-of.ts denies when managed allowedMcpServers is set, or when the plugin/tool name would read as an organization MCP server or organization plugin tool.
  • tool.list reads 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.set lets 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 managed env, managed processWrapper, 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, and wasm.compile from 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/**:

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:

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

Risks

  • mods/…/register.ts fails closed on many policy-read failures. A transient $.settings.read({ source: "policy" }) rejection can deny user tool registration, pin every env.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 $.store and 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.