Presets
A preset is one Markdown file in $ONE_CODING_AGENT_DIR/presets (or the normal
XDG agent directory). It has YAML frontmatter and an optional replacement role:
---version: 1id: reviewername: Reviewermodel: openai/gpt-4.1thinking: hightemperature: 0.2tools: [read, grep, find, ls, evidence_read, finish]mcp_servers: []sandboxes: []description: Careful code review.---Review the requested change and report evidence and risks.Included optional presets
Section titled “Included optional presets”The repository’s extras/presets/ directory contains
four optional workspace presets: coder-junior-qwen,
coder-mid-gpt5-6-terra, project, and researcher. These are source files,
not packaged built-ins: copy a selected file into
$ONE_CODING_AGENT_DIR/presets/ (or the equivalent directory under
XDG_CONFIG_HOME) to make it discoverable. The application does not scan
extras/ automatically.
The coding presets and Researcher include editing and shell tools; Project is
planning-only and has no bash, edit, or apply_patch capability. The
presets may specify model IDs that are not available in every installation;
configure the corresponding provider/model before selecting one. As with any
preset, tool lists narrow the capabilities already granted by CLI options and
parent policy; they cannot grant extra authority. Review these prompt files
before use, especially when copying them from another project version.
IDs must be lowercase filename-matching slugs. Preset files are limited to
256 KiB. Unknown or duplicate YAML keys, invalid types, duplicate IDs, path
escapes (including symlink escapes), non-finite temperatures, and nonempty
sandboxes are rejected. sandboxes must be a list of non-empty strings and
must be empty; sandboxing is not implemented or enforced.
The required schema is integer version: 1, id, and name (non-empty, at
most 120 characters). Optional model must have the form provider/model;
the provider/model must be available when the preset is applied. temperature
must be finite and is normalized using the shared temperature rules. thinking
must be one of off, on, minimal, low, medium, high, or xhigh.
description is at most 500 characters. tools, when present, is a non-empty
list of unique tool names; sandboxes is as described above. The optional
mcp_servers is a list of unique, non-empty, already-trimmed server names.
The Markdown body is the replacement role only, not a task template.
mcp_servers selects configured MCP servers independently of the builtin
tools allowlist. If omitted, it preserves the legacy behavior: MCP access is
not restricted by this preset field and remains governed by the effective
parent/CLI server ceiling and tool policy. An explicit list restricts MCP tools
to the named servers; mcp_servers: [] denies MCP access. Names must match
configured servers when the preset is applied; unavailable or parent/CLI-
restricted selections are reported and cannot widen inherited access. This
server selection is separate from the tools list: listing a server does not
override tool-level or other applicable policy. Reserved packaged IDs cannot
be overridden by user files.
Either allowlist can instead use a quoted wildcard as its sole list entry:
tools: ['*']mcp_servers: ['*']Quote * because unquoted YAML treats it as an alias; the value must be a list,
not the scalar '*'. A wildcard cannot be mixed with names and is not a glob:
[read, '*'] and ['server*'] are invalid. tools: ['*'] admits available
tools dynamically, while mcp_servers: ['*'] admits MCP tools from available
servers separately from the builtin tool list. Both remain subject to inherited
parent and CLI tool and server ceilings, as well as other applicable policy.
For example, tools: ['*'] with mcp_servers: [] still denies MCP servers.
Omitting tools retains its existing behavior; tools: [] remains invalid.
Omitting mcp_servers retains the legacy tool allowlist behavior described
above, unless tools: ['*'] is set: with that wildcard and no explicit
mcp_servers, the preset selects all currently available servers, subject to
inherited server ceilings. mcp_servers: [] still denies MCP access.
Wildcards are dynamic, not a frozen list: newly available tools or servers can become accessible later, including after MCP refresh or reconnect, within those ceilings. Prefer explicit names when future access would be undesirable.
default, readonly, and explore are packaged reserved IDs. User files may
not replace any of these IDs; a collision makes preset discovery fail. Default retains the normal
dynamic prompt, project guidance, skills, and current model settings. Readonly
allows inspection, HTTP(S) GET via web_connect, evidence reads, completion,
and cooperation-gated questions; it denies shell and editing tools at dispatch
time, including refreshed MCP tools. This is app-enforced read-only behavior,
not a network restriction: web_connect can access localhost and private
services reachable to the process, and GET requests may have side effects.
It is an application policy, not an OS sandbox and does not confine extensions
that have already run. While active it denies app-mediated manual shell commands
and does not bind or invoke extension hooks; normal session persistence remains
available. Both Default and Readonly include web_connect.
Existing saved effective preset snapshots are not expanded automatically; reapply
the preset to adopt the new tool list (subject to parent/CLI ceilings).
explore is a focused project investigation role. It searches and reads local
resources, traces relevant behavior, and reports findings with path and line
evidence. Its app-enforced ceiling excludes shell, editing, HTTP, and MCP tools;
its default tool list omits user questions and nested delegation, and explicitly
selects no MCP servers. It handles one bounded assignment, searches before bounded
reads, and returns a concise answer with evidence and any gaps rather than a tool
transcript. Missing information is reported to the requester. Explicit child tool
overrides still follow the normal precedence rules: the reserved Explore ceiling
continues to permit read-only questions and delegation, preserving saved snapshots.
As with Readonly, manual shell commands and extension hooks are blocked, and activation
requires a clean session if extensions have already executed. It is not an OS
sandbox. Use one --preset explore ..., /preset explore, or request
preset: "explore" when spawning a subagent. Existing session snapshots retain
their saved effective settings; explicitly reapply the preset to adopt changes.
Explore does not pin a provider or model: children inherit the parent model unless
spawn_subagent.model explicitly selects another available model. For cheaper
fact gathering, delegate a specific question and source scope before reading the
whole material in the parent; avoid delegation for trivial reads. Instructions
about concise output are guidance, not a hard token or cost budget.
Use one --preset readonly ..., or /preset to list and /preset readonly to
apply an idle session preset in TUI or interactive mode. RPC exposes
list_presets and set_preset. RPC request id is only the correlation key;
use {"type":"set_preset","id":"request-7","presetId":"readonly"}
(or preset) to select a preset. --preset cannot be combined with the replacement
--system-prompt. Subagents may request preset; explicit child model/tools win
over configuration, while parent and CLI capability ceilings always intersect.
Preset files are data, not templates.
Subagent metadata header
Section titled “Subagent metadata header”With the standard resource loader, every system prompt starts with a short
metadata header: Current date, workspace, env, and user_privileges.
This applies to Default and custom preset roles, including nested subagents.
Children reuse the parent’s resource loader and workspace; the header is
generated by the loader, not copied from the parent’s full prompt or inserted
into the delegated task. Tool descriptions are composed for the child’s own
visible tools under inherited capability ceilings.
env describes the operating system, not environment variables.
user_privileges reports detected host-account privileges, not permission to
use tools: Readonly and other application policy restrictions still apply.
The runtime also adds its existing detailed Current Date section with timezone;
this is separate from the short header. Custom embedding loaders can supply
different prompt content; the standard header contract is covered by
tests/test_subagent_metadata_header.py using offline provider requests.
In the TUI main input, Shift+Tab cycles through the /preset discovery order
and wraps from the last preset to the first. It preserves the draft and cursor,
updates the sidebar, and uses the same idle-only activation checks as /preset.
If activation fails, the error is displayed and the current preset is retained.
The next Shift+Tab advances past that failed candidate, so an unavailable model
does not trap keyboard cycling. Explicit /preset id selection still validates
and applies only the requested preset.
Dialogs and open overlays keep their normal Shift+Tab focus navigation.
For a new session the order is explicit CLI provider/model, temperature mode or
temperature, and thinking setting; then preset fields; then the existing resolved
settings. A resumed or forked session restores its saved effective preset snapshot
(including its prompt and restrictions) rather than re-reading a changed file.
Manual model, thinking, temperature, or tool changes retain the preset identity and
are shown as modified. Selecting a preset is rejected while the session is busy.
Explicit CLI/subagent model, temperature, and thinking values override preset
configuration; preset values override ordinary defaults. For subagents, explicit
child model/tools values take precedence over corresponding preset configuration.
Parent and CLI capability ceilings always win, including for tools and MCP
servers selected by a preset. Saved effective session snapshots retain their
server ceilings; changing a preset file does not expand them automatically.
Per-preset model settings
Section titled “Per-preset model settings”Global and project settings.json can configure only the model of a preset:
{"presets": {"overrides": {"explore": {"model": "openai/gpt-4.1"}}}}Project settings take precedence over global settings per field. A project null
model cancels the global override and uses the model in the preset file (or the
normal inherited/default model if the file has none). Unknown fields and invalid
structures are errors. The provider/model must be available when selected; an
unavailable selection is an error, not a fallback. Explicit CLI and subagent
model arguments take precedence. Resume and fork use saved effective snapshots;
reapply a preset to adopt changed settings. The configured model therefore comes
from the project setting, global setting, or preset file in that order, unless
an explicit model or saved snapshot takes precedence.
The interactive /preset list shows the configured model and source. RPC
list_presets and the TUI runtime preset_list DTO include model and
modelSource (project settings, global settings, preset, or inherited).
These describe the next preset selection, not a running session’s saved model.
External edits to settings files require restarting ONE to load them; reapplying
a preset uses the settings currently loaded in memory. Overrides never change
the preset’s tools, instructions, or capability ceilings. Unknown preset IDs in
the settings map remain dormant until a matching preset is selected.