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.md

The filename is the profile name. Names may contain ASCII letters, digits, -, and _, with a maximum length of 64 characters. builtin is reserved.

Add guidance

Plain Markdown creates an overlay profile:

---
description: Review code without modifying it
layout: 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 does not invalidate the prompt cache. 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

Set layout: custom to compose the full main-agent prompt from dynamic Caudra components:

---
description: Security-focused reviewer
layout: 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

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.*": lazy
    "github.delete_issue": disabled

Field	Values	Default
tools.default	inherit, eager, lazy, disabled	inherit
tools.groups	Group name mapped to eager, lazy, or disabled	Empty
tools.overrides	Tool selector mapped to eager, lazy, or disabled	Empty

An eager tool starts with its full schema in the request. A lazy tool is callable and searchable, but initially contributes only a catalog summary. Calling a lazy tool directly by its known name is valid and loads its schema. A disabled tool is absent from schemas and search, and calls are refused before argument repair, permission prompts, or execution.

Loaded schemas remain session-local. Restored history and MCP reconnects cannot re-enable disabled tools.

Resolution goes from the most specific rule to the least specific:

1. Exact tool override.
2. MCP server.* override.
3. Built-in group.
4. Profile default.
5. Existing loading preferences when the default is inherit.

Explicit eager and lazy settings override model-class deferral, agent.defer_builtin_tools, MCP thresholds and always_load, and the eager hint from --allowed-tools. Loading remains separate from synchronous and background execution.

MCP selectors use canonical server.tool names, not provider wire aliases. 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

Group	Members
web	websearch, webfetch
files	file_read, file_write, file_edit, file_apply_patch, file_glob, file_grep, file_index
code_graph	code_map, code_context, code_refs, code_impact, code_expand
execution	shell, python_execution, execution_environment
delegation	task, task_control, workflow
support	batch, question, todo_write, plan
images	view_image, image_generate
messaging	list_sessions, send_message, publish_message, read_topic

Select memory and skill individually. 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. The existing code-graph loading bundle remains, limited to its eligible lazy members. A custom tool using a built-in name does not acquire that built-in's group or infrastructure privileges.

Restrictions and infrastructure

A profile cannot restore tools removed by global or CLI restrictions, disabled experimental features, model compatibility, execution policy, 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. Host-required task-report and structured-output sinks also remain where their protocol needs them. tool_search appears only while an eligible lazy catalog has pending tools. 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

Save this as system-prompts/researcher.md:

---
description: Research online sources and report evidence
tools:
  default: disabled
  groups:
    web: eager
    support: lazy
  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

Save this as system-prompts/scheduler.md:

---
description: Coordinate specialists and track the plan
tools:
  default: disabled
  groups:
    delegation: eager
    support: eager
  overrides:
    workflow: lazy
    plan: lazy
---
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

A profile can select a model and thinking setting for subagents:

---
description: Deep security analysis
layout: overlay
subagent_model: anthropic/claude-opus-4-6
subagent_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.

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.

The task tool accepts profile and mode. 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 are stored with task history. A continuation uses the stored values when they are omitted and rejects conflicting values. Legacy task histories bind both values on their first successful continuation.

The task API no longer accepts subagent_type, model, or model_tier. Replace subagent_type = "research" with mode = "plan" and subagent_type = "general" with mode = "build". Move model selection into profile frontmatter and remove plugins.task.allow_model from your caudra.toml or init.lua.

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 review
caudra --system-prompt-profile review --print "Review this change"
caudra --system-prompt-profile review prompt system
caudra --system-prompt-profile researcher tools
caudra --system-prompt-profile scheduler prompt --plan --tools

caudra tools reports the initial eager, lazy, and disabled set. caudra tools --schemas and caudra prompt --tools show the initial request schemas, including one combined pending catalog when needed. They do not restore a session's previously loaded 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. 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. Profile content stays in the config directory, so edits apply when the session is resumed or Caudra is reloaded.

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.