Skip to main content
An agent’s configuration is its template’s, with the agent’s own values applied on top: the agent’s value wins on a shared name. Some settings reach running sessions; others are fixed when a session is created.

What is fixed per session

When a session is created, paddock composes its session settings from the agent’s effective configuration at that moment: the system prompt, the environment, the permissions, and Claude Code’s small model. They never change for that session. The harnesses read these values only when a process or conversation starts, so fixing them per session means every restart and resume of a session runs on the same values, and no change ever needs a harness restart. Create a new session to pick up new values. A session’s working directory (cwd) is fixed at creation too; see Agents and sessions.

System prompt

The system prompt is text appended to the harness’s own system prompt in every turn; it is never shown as a message. It comes from three places:
  1. The template’s system_prompt.
  2. The agent’s own, which replaces the template’s when set.
  3. The systemPrompt given to sessions.create, appended after a blank line.
The result is stored as the session’s systemPrompt (null when all are empty), at most 64 KiB.
get, set, and delete each return the effective value with its source, template or agent.
Put hard rules about output, such as a required format, both in the system prompt and in the messages that ask for the work. Agents follow rules repeated in the request more reliably.

Environment

On Claude Code, environment variables reach the harness and every command it runs. On Codex, they reach every command Codex runs but not the Codex process itself.
  • Names match ^[A-Za-z_][A-Za-z0-9_]*$, up to 128 bytes; values are UTF-8 up to 16 KiB.
  • These names are reserved, because paddock sets them for the harness: PADDOCK_*, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, OPENAI_API_KEY, OPENAI_BASE_URL, CLAUDE_CONFIG_DIR, CODEX_HOME, HOME, and PATH. Using one is 400.
  • The collection rules of Capabilities apply: add of a template’s name creates the agent’s override, and delete restores the template’s value.

Permissions

Permissions are allow and deny rules in the syntax of the agent’s harness. paddock passes them to the harness as they are and does not interpret them: on Claude Code they become the allow and deny lists of its settings, such as Bash(npm run test:*).
set replaces the agent’s own permissions and returns the effective ones: the effective deny is the template’s and the agent’s together, and the effective allow is the agent’s once it has set one, otherwise the template’s.

Model and small model

The model is the one setting of this page that reaches running sessions: a change is applied between turns, so a turn always finishes on the model it started with. Claude Code’s small model, used for background requests and for subagents that ask for a smaller model, is a session setting.
The agent’s model field is always the effective model. delete() restores the template’s value. Which names you can use is on Models.

Save the result

When an agent’s configuration is what you want for new agents, export it and save it as a template; see Templates.