Defaults, Settings & Who Can Change Them

Step 1Three kinds of knob, and only one of them is a control.

Every agent product ends up with all three, usually without anyone deciding to build them:

• Preference. The operator may change it; changing it is the point. Theme, verbosity, which model, default working directory. Nothing depends on it holding.
• Requirement. The operator may not change it, because someone else accepted the risk. No network egress, no credential tools, this allowlist of MCP servers and no others.
• Capability grant. Not a tuning value at all — it decides what exists. Which tool servers are mounted, which directories are reachable, which skills are loaded. Granting one is not configuring the agent; it is building a different agent.

These three get stored in the same file roughly always, and that is the bug. A requirement in a file the constrained party can write is a preference with a stern comment above it. OpenAI's Codex CLI is worth copying here precisely because it is pedantic about the split: an administrator sets allow_managed_hooks_only = true in requirements.toml to ignore user, project and session hook configuration while still allowing hooks from the requirements and managed-config layers — and the documentation states the setting is supported only in requirements.toml, so putting it in config.toml does not enable the mode at all. The same key is a control in one file and a no-op in another. That looks like a quirk and it is the entire mechanism.

Step 2The default is the policy. Do the arithmetic with your own change rate.

A settings screen distributes outcomes, and the distribution is dominated by the option nobody selects. If r is the share of users who ever move a given setting, your fleet-wide behaviour is a blend, and for the small values of r that settings screens actually produce, the default is the behaviour:

# what a default actually decides, with your own measured change rate
r = change_rate                      # share of accounts that ever move this setting
exposure = (1 - r) * risk_of_default + r * risk_of_chosen

# at r = 0.05, 95% of your fleet is running the value you picked in a sprint
# planning meeting. Moving the DEFAULT one notch is worth ~19x the effort
# spent making the setting easier to find.

# the number you need is r, and you already have it:
SELECT setting, COUNT(*) FILTER (WHERE value <> default_value) * 1.0 / COUNT(*)
FROM account_settings GROUP BY setting ORDER BY 2 ASC;   -- lowest r first

Run that query before the next settings redesign. The rows at the top are not "settings users do not care about"; they are decisions you have already made on everyone's behalf, and they are the ones to argue about in review. A permission default, an autonomy default, a retention default and a model default each set a number for your whole install base, and three of those four are risk rather than taste.

Two corollaries that are easy to act on. First, if a setting's safe value is also its slow or expensive value, the default decides your cost curve too — see cost and quota UX for the user-facing half. Second, your defaults have a dependency you did not choose: when a provider changes its default, your product's behaviour moves without a deploy, which is the failure unpinned vendor defaults exists to catch. Pin the ones that matter and you have decided them; leave them and someone else decides them on a Tuesday.

Step 3The agent reads its own settings, so "turn that off" has three meanings.

This is the property that makes an agent settings surface different from every other settings surface, and it is routinely missed because the UI looks identical. When a user says "stop asking me before you edit files" they could mean any of three things, and your product probably implements the weakest one:

• A sentence in the conversation. The model reads it and complies as a matter of instruction-following. Nothing changed in the system. A later turn, a compaction, a subagent or a sufficiently confident retrieved document can undo it, and the user has no way to tell which regime they are in.
• A stored preference the agent can see and write. Durable across turns, visible in a file, and editable by the thing it governs — so it survives forgetting and does not survive an adversary.
• A requirement outside the agent's reach. Enforced by code the agent cannot modify, in a file it cannot write. The only one of the three that is a boundary.

The design obligation is to make which one is in play legible, because users read all three as the same act. A reasonable rule: a setting changed in conversation is a preference, always, and the UI must say so and show where it landed; anything with a security or spend consequence requires an out-of-band change the agent is not party to. That is not friction for its own sake — it is the difference between ambient authority and an actual grant, and a conversational "sure, I'll stop doing that" is the most convincing wrong answer in agent UX.

While you are here: assume the settings file is read by an adversary as well as the agent. A config that enumerates your MCP servers, endpoints and auth hints is a map, and configuration as reconnaissance is the full argument for why it is one of the better-value files on the machine.

Step 4Name the consequence, not the mechanism.

Agent settings are written by engineers and read by people who do not share the engineer's model of the system, which produces screens full of true statements nobody can act on. "Enable Bash tool" is a correct label and an unanswerable question. The rewrite is mechanical: state what becomes possible, bounded by where.

• Not "Allow shell commands" — but "Run programs on this computer, including ones that change files outside this project".
• Not "Auto-approve read-only tools" — but "Read any file in this folder without asking. Reading is how data leaves, so this includes anything secret stored here."
• Not "Enable network access" — but "Fetch and send data to the internet. An instruction hidden in a page it fetches can then be acted on."

The third example shows why this is more than copywriting. A user who understands "network on" as a convenience toggle cannot be expected to infer the exfiltration leg; naming it is the only way the consent means anything. The rule of thumb is to label a setting with the worst outcome a reasonable person would not have predicted, which is usually one sentence and usually about reads rather than writes. Permission grants and revocation UX covers the grant flow itself, and auto-approval and command allowlists covers why the allowlist behind the friendliest of these toggles is harder than it looks.

Step 5Every setting needs a scope and a lifetime, and "just this once" is the one users want.

The default shape of a settings store — one value per account, forever — is wrong for agent authority, because the thing users actually want is almost always narrower in both dimensions. They want the agent to stop asking for this task, not for all time, and they say "yes, go ahead" meaning the next ten minutes.

So carry both fields explicitly, and let the UI offer the narrow option first:

• Scope. Turn, task, session, project, account, organisation. A permission mode granted at session scope that a product stores at account scope is the single most common way an agent ends up with more authority than anyone granted — the user remembers a decision about one piece of work.
• Lifetime. Until this task ends, until this session ends, until a date, or never expires. Make "never expires" a deliberate selection rather than the absence of one; a grant with no expiry is indistinguishable from a grant nobody reviewed, which is what access reviews then have to find by hand.

Two more rules earn their keep. Re-ask on material change: if the scope the grant was made under has shifted — a different repository, a new tool server mounted, a tenfold jump in the spend the task implies — the old yes does not cover the new situation, and task scope is the general version of pinning a grant to the job that prompted it. And make revocation as reachable as the grant was: the button that turned it on should sit next to the one that turns it off, with a plain statement of what is currently in force. Progressive autonomy covers moving a user up these rungs over time, and the reason it works is that each rung is scoped rather than global.

Step 6Treat a fail-open default as a detection gap, and measure four things.

One class of default deserves naming on its own, because it is where products quietly choose a risk posture: what happens when validation of a configured artefact fails. Cloudflare's Agents SDK 0.32.0, released 29 October 2026, checks every SKILL.md it loads against the Agent Skills specification — and a skill that breaks a rule still loads, with a logged warning, while only a skill that cannot be used at all, such as one with no description, is skipped. That is a defensible default for a specification still in motion, and it is also a decision that every deployment inherits without choosing it. If your product validates skills, hooks, tool schemas or policy bundles, the fail-open-versus-fail-closed choice is a setting whether or not you exposed it, and fail-closed and fail-open is the argument for making it explicit.

Then instrument the surface, because a settings screen is a product with users and almost nobody measures it:

• Change rate per setting. The r from STEP 2. Near-zero means you decided it; treat the next change to that default as a behaviour change requiring the same review as a code change, behind a flag if you have one — feature flags for agents is where that machinery lives.
• Grants by scope and lifetime. The share of live grants that are account-wide and non-expiring. This number only goes up on its own, and it is the one an auditor will ask for.
• Conversational overrides. How often users try to change a setting by saying so. A high count is a missing control and a misleading UI at the same time, and it tells you exactly which setting to move out of the conversation.
• Reverts within a session. Users turning something on and off again inside one sitting means the label did not describe the consequence — this is the cheapest signal that STEP 4 failed, and it needs no survey.