System Prompt Profiles
System prompt profiles change main and task prompts without copying Caudra's built-in prompts. They can also choose which tools are available and which schemas load on demand. Overlay profiles preserve current tool guidance, environment details, instruction files, plugin hints, and mode text.
Profiles are Markdown files in the user config directory:
~/.config/caudra/system-prompts/review.mdThe filename is the profile name. Names may contain ASCII letters, digits, -, and _, with a maximum length of 64 characters. builtin is reserved.
Add guidance
Section titled “Add guidance”Plain Markdown creates an overlay profile:
---description: Review code without modifying itlayout: overlay---
# Review profile
Prioritize correctness bugs, regressions, and missing tests.Do not edit files unless the user explicitly asks.layout: overlay is the default, so the frontmatter is optional. Caudra inserts the profile after runtime context and before the mode section.
The system prompt is identical in plan and build mode, and carries no working directory, date, or model. All of those are announced in the conversation instead, and re-announced only when they change, so switching mode, crossing midnight, or changing model leaves the system prompt as it was. A model switch still starts a new cache. See When Caudra rebuilds. Editing an instruction file mid-session is announced the same way, as a diff against the copy the prompt already carries. Task prompts follow the same rule: a subagent is told its environment and the mode it was granted in the conversation.
Those announcements arrive wrapped in <system-reminder>. They are appended to the conversation and never edited, so a kind is restated only when its content changes or a compaction summarized the block in force, and earlier blocks of the same kind remain as history. The most recent block of a kind is the only one in force; the system prompt tells the model this, and that a reminder is not the user talking.
Control the layout
Section titled “Control the layout”Set layout: custom to compose the full main-agent prompt from dynamic Caudra components:
---description: Security-focused reviewerlayout: custom---
{{caudra.identity}}
# Role
Act as a security-focused reviewer. Report findings before summaries.
{{caudra.context}}{{caudra.tools}}{{caudra.conventions}}{{caudra.completion}}{{caudra.plan}}| Directive | Content |
|---|---|
{{caudra.default}} | The complete current built-in prompt |
{{caudra.identity}} | Resolved built-in or plugin identity |
{{caudra.style}} | Tone and professional objectivity |
{{caudra.tools}} | Tool rules, plugin hints, and efficient tools |
{{caudra.conventions}} | Git, security, and plugin conventions |
{{caudra.completion}} | Completion requirements |
{{caudra.context}} | Instruction files and plugin runtime context. In a task prompt, the instruction files alone |
{{caudra.plan}} | The system-reminder contract, and how plan and build mode work. Identical in both modes |
A directive expands only when it occupies a complete line. Prefix it with \ to keep it literal, for example \{{caudra.tools}}.
Each component directive may appear once. {{caudra.default}} cannot be combined with another component directive. Custom layouts may omit components, though omitting tools, context, or plan can remove information the agent relies on.
Profile files must be valid UTF-8 and no larger than 64 KiB. Unknown frontmatter fields and unknown directives make the profile invalid.
Choose tool availability
Section titled “Choose tool availability”Add a tools block to either layout. It covers native tools, local and remote Workcell tools, MCP tools, Lua/plugin tools, and local callbacks. Omitting it, or writing tools: {}, preserves the existing loading behavior.
tools: default: inherit groups: files: disabled overrides: file_read: eager "github.*": eager "github.delete_issue": disabled| Field | Values | Default |
|---|---|---|
tools.default | inherit, eager, disabled | inherit |
tools.groups | Group name mapped to eager or disabled | Empty |
tools.overrides | Tool selector mapped to eager or disabled | Empty |
An eager tool is available: its schema is in the request, or for a tool the model reaches from code, its module answers. A disabled tool is absent, and calls are refused before argument repair, permission prompts, or execution. lazy was removed with tool_search, and a profile that uses it fails to load.
MCP tools never put a schema in the request, because the model calls them through code mode. For them, disabled refuses their calls. Restored history and MCP reconnects cannot re-enable disabled tools.
Resolution goes from the most specific rule to the least specific:
- Exact tool override.
- MCP
server.*override. - Built-in group.
- Profile default.
- Existing loading preferences when the default is
inherit.
Availability remains separate from synchronous and background execution.
MCP selectors use server.tool names, with the server's configured name and the tool's own MCP name, not the Python names the model calls. Plugin and custom tools use their exact registered names. Unknown groups, invalid states, malformed selectors, duplicate keys, and reserved infrastructure selectors are errors. Bare custom names must resolve in the runtime registry before the profile can run. Qualified MCP selectors may precede a server connection, but an unavailable tool grants no access. Arbitrary globs, custom groups, and profile inheritance are unsupported.
Tool groups
Section titled “Tool groups”| Group | Members |
|---|---|
web | websearch, webfetch |
files | file_read, file_write, file_edit, file_apply_patch, file_glob, file_grep, file_index |
source_code | source_code_context, source_code_refs |
execution | shell, execution_environment (host in code) |
delegation | task, task_control, workflow (workflow and automation in code) |
support | batch, question, todo_write, plan |
images | view_image, image_generate (image in code) |
messaging | list_sessions, send_message, publish_message, read_topic |
Select memory and skill individually. code is always available, so a profile that disables it fails to load. A group that turns off a tool reached from code makes its module raise with the reason. Messaging is optional and separate from support and delegation. It still requires its experimental opt-in, an eligible main-session runtime, peer inbound controls, and outgoing permissions.
Groups are authoring shortcuts. They do not guarantee that every member exists in a runtime or cause members to load together. A custom tool using a built-in name does not acquire that built-in's group or infrastructure privileges.
Restrictions and infrastructure
Section titled “Restrictions and infrastructure”A profile cannot restore tools removed by global or CLI restrictions, disabled experimental features, model compatibility, audience, or mode. A task in plan mode stays read-only. Permissions still authorize each call, and explicit denies remain effective.
The trusted tool_output pager stays available for truncated results, and code stays available as the home of the modules. Host-required task-report and structured-output sinks also remain where their protocol needs them. These are infrastructure exceptions, identified by their trusted bindings. todo_write, question, batch, plan, memory, skill, task, and workflow require normal opt-in under default: disabled.
Tool availability is not a sandbox. Permitted shell commands, trusted plugins, and delegated tasks can perform broader work. Profiles do not isolate prompt history or sandbox plugin code.
Web researcher
Section titled “Web researcher”Save this as system-prompts/researcher.md:
---description: Research online sources and report evidencetools: default: disabled groups: web: eager support: eager overrides: todo_write: eager---Research the question using online sources. Cite evidence and distinguish uncertainty.Remove support and the override for a web-only profile with just the required infrastructure.
Main-agent scheduler
Section titled “Main-agent scheduler”Save this as system-prompts/scheduler.md:
---description: Coordinate specialists and track the plantools: default: disabled groups: delegation: eager support: eager---Delegate research and implementation to appropriate task profiles.Coordinate results, maintain the todo list, and keep the session plan current.This actor cannot call file, web, or shell tools directly. It can delegate to a task using profile: researcher, another coding profile, or profile: builtin. Each task resolves its own selected profile against the inherited CLI, config, mode, and security restrictions. The parent's profile-local mask is not inherited as a global restriction. Tool compatibility is recalculated for the worker's model. Omitting profile still selects the parent's profile, so an omitted profile keeps the scheduler's tool choices.
This independence applies to Caudra's audited task delegation path, including workflow-created tasks and nested task calls. Ordinary Lua tool calls retain the current actor's policy. Generic/custom subagent APIs can only narrow their caller's effective access.
The single plan tool reads or replaces this session's plan through the same interface for local and remote workspaces. It has no model-supplied path, reference, or session selector. It is available once the session has a plan, which it gets the first time it enters Plan. The main agent can then read and replace the plan in Plan and Build. Saving cannot approve a plan or switch modes. Secure plan storage currently requires a Unix client, including for remote workspaces.
Implement and Clear-and-Implement capture validated plan content before they switch to Build or clear the session. The content is included in the model-visible Build request, so a scheduler does not need file access to receive it. If capture fails, the plan remains available and implementation does not start.
Configure subagents
Section titled “Configure subagents”A profile can select a model and thinking setting for subagents:
---description: Deep security analysislayout: overlaysubagent_model: anthropic/claude-opus-5-5subagent_thinking: high---
Prioritize exploitable findings and concrete fixes.subagent_model accepts an exact qualified provider/model name or the same-as target chat, plan, fast, or best. A named target follows that job's current binding and default. A profile value overrides the global Subagent binding. If the profile omits it, the global binding applies. When both are unbound, the subagent inherits the model currently running its parent.
subagent_thinking accepts off, adaptive, an effort level, or a positive token budget. It inherits the parent's thinking setting when omitted. These fields do not change the main agent. See Model jobs for routing rules.
A model or thinking set on the task call wins over these fields for that task. The main agent sets one when you ask for a model or a reasoning level. See Models and reasoning.
Caudra validates each profile against the effective subagent model. An explicit thinking setting must be supported exactly. Caudra does not snap effort levels, clamp budgets, or translate between effort and budget modes for a profile. An incompatible profile remains available to the main agent, but Caudra warns and removes it from the task profile list. A task that sets its own model or thinking skips this check and snaps the level to its model.
The task tool accepts profile, mode, model, and thinking. A new task inherits the parent profile when profile is omitted. Set profile to builtin to use Caudra's built-in task prompt.
mode defaults to the caller's own mode and can never exceed it, so a task launched from build mode can build, and one launched from plan mode stays read-only. plan has a host-enforced read-only tool set with no file writes. Eligible shell calls must pass the host's confined read-only checks. A task that needs mutating commands requires build. A build request from a plan-mode caller runs as plan instead. Every result reports the mode the task ran as. A task in either mode can read the session plan but cannot replace it. See Read-only agents.
Task profiles support overlay and custom layouts. For a custom task prompt, directives resolve to the matching research or general task component. {{caudra.default}} expands to the complete built-in task prompt. Caudra appends the system-reminder contract after the rendered profile, so custom layouts cannot remove it.
The effective profile and mode, and any model or thinking the call set, are stored with task history. A continuation uses the stored values when they are omitted and rejects conflicting values. Legacy task histories bind profile and mode on their first successful continuation.
The task API no longer accepts subagent_type or model_tier. Replace subagent_type = "research" with mode = "plan" and subagent_type = "general" with mode = "build". Put a standing model choice in profile frontmatter and remove plugins.task.allow_model from your caudra.toml or init.lua.
Built-in task profiles
Section titled “Built-in task profiles”With the pstack skill on, two more profiles appear in the task profile list:
| Profile | Does |
|---|---|
pstack-poteto-agent | Writes code or runs a helper step that a poteto-mode run delegates. It loads pstack/poteto-mode before any work |
pstack-comment-sicko | Deletes comments in a diff or a set of files, apart from a short list of exceptions such as license headers and API docs, and marks code that needs a rename or refactor instead. It never writes application code |
Their text is pstack's own agent files, translated for Caudra. A file of the same name in system-prompts/ replaces one, even a file that fails to load. With pstack = false they are gone, and a task that names one fails as a missing profile does.
Select a profile
Section titled “Select a profile”Set the default in caudra.toml:
[agent]system_prompt_profile = "review"Use builtin to clear a default inherited from another config file.
Override the default for one invocation:
caudra --system-prompt-profile reviewcaudra --system-prompt-profile review --print "Review this change"caudra --system-prompt-profile review prompt systemcaudra --system-prompt-profile researcher toolscaudra --system-prompt-profile scheduler prompt --plan --toolscaudra tools reports which tools are on and which are off. caudra tools --schemas and caudra prompt --tools show the request schemas. Inside a session, /tools provides a mode-aware inventory.
Inside the TUI, run /system-prompt to read the prompt the current session is sending. The modal shows the text the agent bound, so it matches what the provider received rather than a fresh assembly of it. After you edit the session's profile, it keeps that text until the prompt is rebuilt, under a notice that the profile changed. Run /reload to rebuild it now. Press r to swap between rendered markdown and the source, y to copy, and p to open the profile picker.
Drag the pointer to select a passage, and releasing the mouse button copies it without the line numbers. Press Ctrl+A to select everything. With a selection standing, y and Ctrl+C copy it the same way. With nothing selected, y copies the whole prompt source and Ctrl+C closes the modal.
Line numbers count source lines in both views. A rendered row is numbered by the line it draws from, so a heading row and the code inside a fence point at the text you would find at that line in the profile file. A line too long for the modal is folded across several rows and numbered once, at its head.
Switching a profile from that picker stores the selected name with the session and rebuilds the system prompt, so the next request reads the whole conversation at full price. Profile content stays in the config directory. In the TUI, a saved edit applies from the next turn, and the model reads the change as a reminder until its system prompt is rebuilt. See Edit a system prompt profile. Elsewhere, edits apply when the session is resumed. A profile deleted or broken while a session uses it stays loaded in that session as it was. A profile that fails to load shows a red [system prompts invalid] chip in the status bar until it loads again.
A selected profile that is missing or invalid is rejected across the TUI, print/headless, SDK, and ACP. Caudra does not fall back to unrestricted built-in behavior. Select builtin explicitly to reset it.
An explicit CLI profile takes precedence over the stored session profile and the configured default. It applies only to that invocation, so the picker cannot switch profiles until the next invocation.
--system-prompt-profile and the raw SDK --system-prompt override cannot be used together. A raw SDK override continues to replace normal prompt assembly.
Profiles affect the main TUI, print, SDK, ACP, prompt inspection, /btw, and task prompts. Compaction and goal evaluation prompts remain host-controlled.