surshar / 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.

Built by Anthropic · github.com/anthropics

claude-code / mods / sec-default / README.md

Alice T'Poteatsec-default: a settings deny rule holds over an allow or ask from a plugin the person installed (#98080) 16da1ec · 25 days ago History

187 lines · 10.9 KBPreview CodeRaw

1	# sec-default
2
3	The security default for organizations. Function hooks give every plugin a
4	say on every event, in chain order, and the plugins a person installs sit
5	in the user tier, beneath the organization's prepend tier and above its
6	append tier. Some of what an organization sets today (its classic hooks,
7	its managed CLAUDE.md and rules, its settings, its MCP allowlist, the deny
8	rules in force on its machines) was never within a person's reach before
9	function hooks; seated outermost, this plugin keeps exactly those out of the
10	user tier's reach and adds no policy of its own. Everything else passes
11	through untouched.
12
13	It has three moves and nothing else: continue past the user tier
14	(`next.to(e, "append")`), refuse a user-tier caller or module by name
15	(`{ deny }` when `next.origin.tier` is `user`, `{ refuse }` when a module's
16	pinned `e.tier` is), or pass (`next(e)`). A subject's provenance is the
17	event's pinned `e.provider`; policy is read through
18	`$.settings.read({ source: "policy" })`, one read serving a burst of tool
19	calls; both fail closed, so an unreadable policy counts as a policy in force.
20
21	`hooks/register.ts` is the module; `hooks/policy/` reads the managed
22	settings it decides by.
23
24	## The rows
25
26	\| event \| from the outermost seat \|
27	\| --- \| --- \|
28	\| `classic.*` \| Continue past the user tier: the organization's settings hooks see the engine's input and their answer stands. \|
29	\| `prompt.section`, `prompt.context`, `skill.prompt`, `attribution.text` \| Continue past the user tier: managed CLAUDE.md, rules and policy skills reach the model as written. A person's plugins keep `prompt.submit` and its additive context. \|
30	\| `settings.read` \| Continue past the user tier: no user hook rewrites what any caller reads as settings, this plugin's own policy reads included. \|
31	\| `tool.describe`, `command.describe`, `agent.offer`, `agent.spawn` \| When the subject's pinned `e.provider.tier` is `prepend` or `append` (a policy-installed plugin, the managed folder, a policy MCP server), continue past the user tier; a subject provided by `user`, `builtin` or `core` passes. \|
32	\| `tool.register` \| A caller in `prepend` or `append` continues past the user tier. A `user`-tier caller is refused by name while managed settings hold `allowedMcpServers` (set at all, empty included); otherwise it passes. \|
33	\| `tool.list` \| The tools of the organization's managed MCP servers are listed as the organization's tiers listed them; every other tool as the user tier left it. With no policy to read, or a refusal from either listing, the organization's listing stands whole. \|
34	\| `tool.check` \| A deny that a settings rule decided holds over the user tier: when a person's plugin loosened the verdict it was handed, the dispatch is run again past the user tier, and if that verdict is a deny naming its rule, it is the answer. See [Deny rules hold](#deny-rules-hold). Every other verdict passes as the chain left it. \|
35	\| `plugin.register` \| A hooks module in the `user` tier (one a person installed, named with `--plugin-dir`, or keeps in their mods folder) is refused while managed settings set this plugin's `allowManagedModsOnly` option; otherwise it passes. Modules in `prepend`, `append` and `builtin` are never asked about. \|
36	\| everything else \| Passes: `prompt.submit`, `turn.`, `tool.call`, `command.run`, `command.register`, `session.`, `ui.`, `fs.`, `http.fetch`, `process.run`, `store.`, `clock.`, `model.`, `mcp.call`, `audio.`, `agent.list`, `engine.create`. \|
37
38	## Options an administrator sets
39
40	Two, in managed settings, under this plugin's own `pluginConfigs` entry,
41	keyed by the id the CLI builds the plugin in under (only this spelling of the
42	id is read):
43
44	```json
45	{
46	"pluginConfigs": {
47	"cc-plugin-sec-default@builtin": {
48	"options": { "allowManagedModsOnly": true }
49	}
50	}
51	}
52	```
53
54	`allowManagedModsOnly`: only the mods the organization deploys through
55	managed settings, and the ones built into Claude Code, load. A hooks module
56	a person installed, named with `--plugin-dir` or keeps in their mods folder
57	is refused whenever it loads or reloads (one already running when the option
58	is set keeps running until then), with one line that names it: `mods are
59	limited to your organization's by policy (allowManagedModsOnly); <plugin>
60	was not loaded`
61	(in the debug log, and on screen where the session hot-reloads the mod's
62	folder). A plain `-p` run has it in the debug log alone; the mod is still
63	not loaded. Settings hooks, status lines and `/goal` are not touched by it.
64
65	- The decision reads the tier the CLI pins on the module and nothing the
66	module says of itself: a person's copy carrying an organization mod's name
67	is still in the `user` tier and is refused.
68	- Refused means nothing of the module joins: no hook, no tool, no command.
69	Its top-level code has run once by then, in the closed context every hooks
70	module is evaluated in, with no call on `$` served.
71	- Only managed settings are read (`$.settings.read({ source: "policy" })`):
72	the same entry in a person's, a project's or a `--settings` file neither
73	turns it on nor off. On unless absent or `false`, so a mistyped `"true"` or
74	`1` still locks. A value the settings schema rejects (`null`, an object),
75	here or in any other `pluginConfigs` entry, makes the CLI ignore the whole
76	`pluginConfigs` key with a settings warning, and the option reads as unset.
77	- It fails closed: when the read of managed settings is refused (a hook beneath
78	denies it) or this plugin's hook fails, its `.catch` refuses the module,
79	with the same line, and names the failure in the debug log; so a policy
80	that cannot be read keeps every person's mod out at load. Where this plugin
81	is not seated there is no such rule, and mods load as they do without it.
82	- Where managed settings define `prependPlugins`, that list must name this
83	plugin (next section) for the option to apply.
84	- `claude plugin test` is not covered: it runs a mod's tests in an engine of
85	their own and loads nothing into a session.
86
87	`allowModsToOverrideDenyRules`: the plugins a person installs may answer
88	over a settings deny rule on `tool.check`, as they could before this plugin
89	held deny rules. Off unless it is the literal `true`; an option that reads
90	as unset leaves deny rules holding. See [Deny rules hold](#deny-rules-hold).
91
92	## What it hooks
93
94	`classic.*`, `prompt.section`, `prompt.context`, `skill.prompt`,
95	`attribution.text`, `settings.read`, `tool.describe`, `command.describe`,
96	`agent.offer`, `agent.spawn`, `tool.register`, `tool.list`, `tool.check`,
97	`plugin.register`.
98
99	Hooking `tool.check` has a cost: the engine raises that event only when some
100	loaded plugin hooks it, so where this plugin is seated every tool call now
101	runs the `tool.check` chain, where before only a session with such a plugin
102	did.
103
104	## What it calls on `$`
105
106	`settings.read`, and `ui.log`: to the debug log, and for the one line a
107	person reads when a deny rule held over a plugin of theirs. It continues to
108	the `append` tier with `next.to`, which only a plugin in a managed tier may
109	do.
110
111	## Deny rules hold
112
113	On `tool.check` any hook may answer any verdict, so a plugin a person
114	installs to stop the permission prompts (`() => ({ decision: "allow" })`)
115	would also lift a deny rule, a managed one included. Where this plugin is
116	seated it does not:
117
118	- The hook first runs the chain as it is. If the answer is a deny, or no
119	link that may hold a person's plugin answered more permissively than the
120	verdict handed up to it, the answer passes: nothing of the person's
121	loosened anything, and a plugin that only listens adds no run of its own.
122	This is read off `next.trace`, whose tiers the engine pins: a link that never
123	called `next` is measured against a deny, and since the engine lists
124	neighbouring plugins that share a worker as one batch under its first
125	member's tier, a `prepend` entry beneath this plugin counts as well as a
126	`user` one. Whether a person's plugin did the loosening is never settled
127	here, only by the next step.
128	- Otherwise it runs the dispatch once more with the user tier left out
129	(`next.to(e, "append")`). That verdict never passed through a person's
130	plugin, so neither the decision nor the rule it names can have been
131	rewritten or erased, and a plugin that answered without calling `next`
132	changes nothing: the rules are evaluated in this run. The two runs differ
133	by the user tier alone, so a deny here that names its rule is a deny rule
134	the user tier loosened, and it is returned in place of the chain's answer.
135	- Any deny rule counts, whatever settings file it came from: a verdict
136	carries the rule as written, never where it was read from. A deny that
137	names no rule (a settings hook's, a tool's own check) is not held.
138	- An organization's plugin (prepend or append) or a built-in that allows
139	over a deny rule takes part in both runs, so its answer stands (a prepended
140	one that loosens is what brings the second run about, so its hooks run
141	twice on such a call). An ask
142	that a person's plugin turns into an allow, with no deny rule behind it,
143	stands: that is what such a plugin is for.
144	- `tool.check` pins the question (`tool`, `input`, `tool_use_id`), so no hook
145	can have the rules evaluated on one command and another run; a rewrite
146	belongs to `tool.call`, which runs before any of this.
147	- The person is told once for each name in a session, in the transcript
148	and the debug log: `<plugin> tried to lift a deny rule in your settings
149	from a <tool> call (<rule>); the deny rule holds over the plugins you
150	install (allowModsToOverrideDenyRules)`. Plugins the engine ran as one
151	batch are named together, as it names them (`audit+easy`). A plain `-p`
152	run has it in the debug log alone; the call is still denied with the
153	rule's own message.
154	- If the hook itself fails, its `.catch` answers from the one run it can
155	read: a deny stands; a verdict no plugin of the person's loosened stands;
156	one they loosened, or a run that rejected, is refused, since the deny
157	rules were never consulted.
158
159	An organization that wants the plugins its people install to override deny
160	rules says so in managed settings, under this plugin's own options:
161
162	```json
163	{
164	"pluginConfigs": {
165	"cc-plugin-sec-default@builtin": {
166	"options": { "allowModsToOverrideDenyRules": true }
167	}
168	}
169	}
170	```
171
172	Only the managed source is read (`$.settings.read({ source: "policy" })`),
173	so the same key in a person's, a project's or a local settings file, or in
174	`--settings`, is never consulted; only the literal `true` counts, and a
175	policy that cannot be read leaves deny rules holding.
176
177	## Where it is seated
178
179	The CLI seats it first in the prepend tier wherever hooks modules load on a
180	machine with managed settings or for a Team or Enterprise organization,
181	unless managed settings define `prependPlugins`: then that list is the
182	whole prepend tier, and the organization names `sec-default@builtin` in it
183	at the position it wants, e.g. `"prependPlugins": ["acme-guard@acme-tools",
184	"sec-default@builtin"]`, or leaves it out. It is a plugin folder like any
185	other, but its one move that matters, `next.to`, is refused outside a
186	managed tier, so loading it with `--plugin-dir` seats a plugin that can
187	only pass.