# Customizing bundled agents

[Documentation index](../README.md)

Matching global definitions partially override bundled roles.

This allows local customization while continuing to inherit future bundled
changes for omitted fields.

## Minimal model override

```markdown
---
name: reviewer
model: openai-codex/gpt-5.6-luna
thinking: high
---
```

The bundled reviewer body and omitted frontmatter remain inherited.

## Frontmatter merge rules

For a matching global definition:

- omitted fields inherit;
- strings and booleans replace;
- arrays replace wholesale, including `[]`;
- the complete effective definition is validated after composition.

`enabled` is a boolean that defaults to `true`. Use it in a minimal override to
disable a bundled role without copying its body or other frontmatter:

```markdown
---
name: reviewer
enabled: false
---
```

The disabled row remains visible to the root supervisor, while parent-visible
definition lists omit it. A parent referencing a disabled child can remain
discoverable, but is rejected during assignment or fresh worker startup with an
explicit disabled-child reason.

There is no compatibility layer or second definition registry.

## Body composition

An empty override body inherits the bundled body.

A non-empty override body replaces it by default:

```markdown
---
name: reviewer
---

Use this completely different reviewer behavior.
```

Use `bodyMode: append` to preserve the bundled body and add local behavior:

```markdown
---
name: reviewer
bodyMode: append
---

Also verify database migrations.
```

When both bodies are non-empty, append mode produces one blank line between the
bundled and override bodies.

`bodyMode` is valid only in a global definition matching a bundled definition.
It is consumed during definition composition and does not become runtime
frontmatter.

## Runtime system-prompt composition

`bodyMode` and `systemPromptMode` solve different problems:

```text
bundled body + override body
          ↓ bodyMode
effective definition body
          ↓ systemPromptMode
Pi base system prompt
```

`systemPromptMode: replace` sends the effective body as Pi's replacement system
prompt.

`systemPromptMode: append` appends the effective body to Pi's normal system
prompt.

Managed workers additionally receive shared Herdr worker guidance at launch,
including the `ask_owner` contract. This shared guidance is infrastructure and
is not copied into every bundled role body.

## Add local body files

```markdown
---
name: reviewer
bodyMode: append
---

@./prompts/local-review-policy.md
```

The path is resolved relative to this override file before body composition, so
bundled and override references preserve their own declaring-file provenance.

References expand when a new worker generation is constructed. A live reusable
worker keeps the prompt established when it was launched.

See [Handoffs and files](handoffs.md).

## Local tools, skills, and extensions

Bundled definitions are portable by design. Add local capabilities in the
matching global override.

Example:

```markdown
---
name: reviewer
bodyMode: append
tools: ["read", "bash", "my_local_tool"]
skills: ["/absolute/path/to/code-review/SKILL.md"]
extensions: ["/absolute/path/to/local-extension.ts"]
---

Use my local tool only when it materially improves the review.
```

Remember that arrays replace the bundled array rather than append to it.
Explicitly include every value you want in the effective array.

Skill and extension paths are passed to Pi unchanged; unlike body `@file`
references, Herdr does not resolve them relative to the definition file.

## Interactive model and reasoning overrides

Root supervisors with UI can use:

```text
/subagents overrides
```

The menu operates only on extension-backed definitions and can:

- set model;
- reset model;
- set reasoning;
- reset reasoning;
- disable an agent;
- enable an agent.

It changes only the selected top-level line in the global Markdown override and
preserves unrelated frontmatter, line endings, and body content.

Reset removes the saved field so the bundled/current value is inherited again.
The override file is not deleted.

Enable and disable write the scalar `enabled` field in the same global override.
Removing that field inherits the bundled value, or `true` when no source
declares it.

Changes affect future fresh starts and non-live historical-session resumes,
whose runtime configuration comes from the current effective definition. They
do not mutate an already-running worker or a live reusable resume, whose launch
configuration is frozen, or the root supervisor.

## See also

- [Agent-definition schema](../reference/agent-definition-schema.md)
- [`/subagents` commands](../reference/commands.md)
- [Agent definitions](agent-definitions.md)