Agent Profiles

Profiles define agent behavior: prompts, hooks, environment defaults, and reintegration policy. The canonical format is Markdown with YAML frontmatter. Profiles are runtime-agnostic by default; runtime-specific limitations are enforced through explicit feature compatibility checks, not profile-level allowlists.

Profile Format

---
name: worker
description: Implement the next ready bead.
skills: []
mcp_servers: []
permission_mode: bypassPermissions
memory: project
hooks:
  on_start:
    - type: command
      command: caco agent status set "starting"
      timeout: 10
  post_tool_use:
    - matcher: "Bash|Edit|Write"
      hooks:
        - type: command
          command: caco msg speak "Continuing work"
          timeout: 5
reintegration:
  mode: direct
---

Implement the assigned bead, validate it, and report completion.

Profile Fields

Frontmatter

Cross-project bead permission mixins are intentionally explicit. cacophony-bead-scope grants least-privilege Cacophony-only mutation for orchestration/runtime follow-up work, while global-bead-scope grants create/update/claim/close permissions across all currently configured projects for dedicated global board triage or repair roles. Composing multiple bead-scope mixins intersects their grants rather than unioning them, so use one scope mixin at a time unless the intersection is intentional.

Release skew. Daemons resolve shipped profiles from the default branch, which can be newer than the release they run. At runtime, a value outside that release's closed vocabularies (reintegration modes, MCP servers, permission modes, hook mixins, authorization capabilities, message subscriptions, lifecycle operations, bead actions, and inbox sender classes) is ignored with a one-line daemon warning instead of failing the profile, and an allowlist left empty denies everything. Scalars whose default would be broader, such as authorization.scope, stay strict. caco config validate stays strict too, and repository validation rejects a shipped profile that uses a value caco_profile::vocabulary::VOCABULARY_INTRODUCTIONS records as newer than the workspace release: land the code first and change the profile after the next release ships.

Body

The Markdown body after the frontmatter contains prompt material and instructions for the agent.

Hook Phases

Hook Entry Structure

hooks:
  on_start:
    - type: command                 # Required: action type
      command: caco bd claim        # For type=command
      timeout: 10                   # Optional: timeout in seconds
  post_tool_use:
    - matcher: "Bash|Edit|Write"    # Optional: limit to matching tools
      hooks:                        # Nested hooks
        - type: command
          command: caco msg speak "Continuing"
          timeout: 5

Hook Action Types

Currently supported:

• command — executes a shell command in the agent's context

Unknown action types are rejected at validation time, not silently dropped. Tool matchers use pipe-separated exact names; nested matcher groups skip all child hooks when the current tool is absent or does not match. Codex-managed profiles use Codex’s own trust surfaces: operators may persist [hooks.state."<hook-key>"].trusted_hash in config or define managed hooks in requirements.toml with [features].hooks = true and [hooks].managed_dir; Cacophony does not silently forge trust for non-managed hooks.

Reintegration Modes

Modes can be composed with the recorded suffix (e.g. direct,recorded) to require a session-recording summary artefact at .cacophony/agent/<id>/summary/<NNNN>/summary.md before the merge proceeds. See the session-recording mixin.

Project config can also set projects[].integration.default_intent and projects[].integration.backend. For example, a profile whose default mode is pr_review opens a review PR by default, while backend: pull_request lets even direct/review intents use the declared fork/upstream topology rather than ad hoc checkout remotes.

Agent Compatibility

The canonical profile format is Claude-style (Markdown + YAML frontmatter). Agent types that don't natively consume this format are supported through bridges:

Example: Default Agent Profile

---
name: agent
description: General-purpose Cacophony agent.
hooks:
  on_start:
    - type: command
      command: caco agent status set "starting"
      timeout: 10
  on_complete: []
reintegration:
  mode: direct
---

You are a Cacophony agent. Follow the project conventions,
implement assigned work, validate with tests, and report completion.

Example: Bead Implementer Profile

---
name: worker
description: Claim and implement the next ready bead.
hooks:
  on_start:
    - type: command
      command: caco bd claim
      timeout: 10
  on_complete:
    - type: command
      command: 'caco bd close "${CACO_BEAD_ID:?set bead id}"'
      timeout: 10
reintegration:
  mode: direct
---

Claim the next ready bead, implement it following the project spec,
run tests, commit with the bead ID, and report completion.

Validation belongs to branch protection and CI: there is no daemon reintegration gate, and a PR merges only once its required checks pass. See the delivery model.

Embedded Profiles, Flows and Pi Overlays

The caco binary embeds the checked-in .cacophony/profiles catalog, the Cacophony project flows and the .cacophony/pi overlays at build time, so an agent needs no Cacophony canonical checkout to compose its profile. A profile's pi_extra_config_dirs entry that names a canonical-checkout overlay is materialized from the binary into <agent>/pi-overlays/<name> at spawn, relaunch and refresh, replacing stale files; any other entry, such as a developer's own worktree overlay, is used as written. caco profile list and caco profile show report which repository, user or embedded source each profile came from.

Config-Based Profiles

Profiles can also be defined inline in config.yaml:

profiles:
  - name: agent
    hooks:
      on_start:
        - type: command
          command: caco agent status set "starting"
          timeout: 10
      on_complete: []
    reintegration:
      mode: direct

Persistent Agent Restart Policy

Persistent agents support a granular restart policy that controls when the daemon auto-restarts the agent after it exits:

The restart policy is set on the persistent agent declaration itself, often inside a projects.yaml entry (for this repository, in the separate cacophony-config repository) under projects.<project>.agents.persistent:

projects:
  cacophony:
    agents:
      persistent:
        my-agent:
          imports:
            - agents/persistent.yaml
          profile:
            - technical-writer
          restart: failure         # failure | always | never
          restart_backoff_secs: 30 # minimum backoff between restart attempts

Composed reintegration policy carries mode, allowed_modes, push_tags, auto_rebase_retry_limit and dry_run_gate, each taken from the most specific profile that sets it.

To see how a stack resolves without launching anything, run caco profile compose --dry-run <profile>… (or --agent <declaration>). Each field shows its value, the profiles that contributed and the merge rule used: concatenation, union or intersection for lists such as skills and MCP servers, last-wins for maps and scalars, and must-agree fields flagged when profiles conflict. --summary-only shows just the counts; --show-prompt adds the composed prompt.

Shared agent snippets under agents/ in the config repository are role-scoped rather than one universal persistent stack.

• Claim precedence: When the general dev profile is composed with auto-claim, the intended precedence is explicit user/controller instruction first; if no instruction is pending, the worker may claim ready queue work from the open board instead of waiting indefinitely. If that worker deliberately unclaims an out-of-lane bead, the follow-up no-ID claim may use the request-scoped --exclude-bead-id skip list so the same worker does not immediately reclaim the bead it just declined.
• This fleet's config: The shared pi-common.yaml now composes pi-home-override so checked-in Pi workers pass the operator-owned ~/.pi/agent directory directly instead of materializing a managed copy. The checked-in phone-class sgu24 dev workers are split into caco-dev-s24-codex and caco-dev-s24-pi, both composing the caco-mobile mixin so local heavy builds/tests/emulators are avoided and validation is routed to queued or stronger-node surfaces.

Git Remotes

Profiles can declare named git remotes that the daemon automatically configures in agent checkouts after creation:

---
name: update-helper
git_remotes:
  github: ssh://git@github.com/org/repo.git
---

This eliminates the need for agents to manually run git remote add. The agent can immediately push via git push github main. When multiple profiles are composed, remote maps are merged with later profiles winning on key conflict.

Shell RC

Profiles can include inline shell initialization content that is sourced into every agent shell session before the runtime launches:

---
name: worker
shell_rc: |
  gh() { if command -v gh >/dev/null 2>&1; then command gh "$@"; else echo "gh not available"; fi; }
  export EDITOR=vim
---

Shell RC content is layered by concatenation across config levels: global shell_rc → project shell_rc → profile shell_rc. Later layers can override earlier functions. Content must work in both bash and zsh.

Persistent, One-Shot, Composite, and Mixin Profiles

Profile lifecycle and runtime-stack guidance has moved to Profile Lifecycle and Runtime Stacks to keep lifecycle guidance separate from routine field and shipped-profile reference updates. In short: one-shot workers claim and finish one bead, interactive composites wait for operator direction, persistent specialists/observers run indefinitely under role-scoped snippets, and mixins add behavior through composes without becoming standalone launch targets.

The companion page covers compact autonomous role guidance, daemon-native heartbeat/direct delivery, retired compatibility mixins, intentional pi-home-override, and supported prompt/resource refresh without disturbing operator sessions.

Shipped Profiles

The canonical controller and project-controller profiles carry the narrow agent_spawn_overrides capability. Other agent callers retain mandatory project spawn defaults and may only add an allowed profile specialization.

The persistent test-user declaration uses a lightweight agent-default snippet instead of the generic dev-worker base. It composes Pi runtime, narration, Tendril, image, tmux, and git-check helpers, but deliberately omits implementation/reintegration mixins such as self-improvement, merge-queue, session-recording, and reflect-session. The role is read-only from a source-code perspective: exercise product surfaces, keep scratch state, speak findings, and file beads for observed issues.

The canonical cluster controller profile treats major remediation as operator-gated work: before mass revival, destructive recovery, or other cluster-wide corrective action, it should narrate the issue and block on caco choices. Only a narrow emergency fallback is allowed when the system is too degraded to present choices, capped at one caco restart attempt and then at most one caco update attempt. It also treats brief daemon unreachable and hook/request failures immediately after restart, update, or config rollout as transient restart-window symptoms that should be retried and rehydrated before being escalated into a new incident. It may also use mid-flight caco agent reintegrate for operator-directed controller-profile, documentation, or control-plane maintenance changes without stopping.

The canonical project-controller profile requires explicit startup wake-path handling for Pi-managed persistent runs. It should inspect the first-party /loop state, create profile-required runtime loops when absent, and report newly armed loops as armed / verification pending until a real loop prompt fires. When the pi-loop mixin is composed, /loop is the preferred runtime-native per-agent wake path; do not create daemon-global caco cron entries for self-check or burndown loops unless the host profile or operator explicitly asks for daemon cron. The repo-owned /loop extension suppresses duplicate prompt deliveries for the same prompt/delivery mode when catch-up or duplicate ticks fire within the bounded duplicate-delivery window, while still allowing the next normal interval delivery. Report degraded autonomy only when no runtime-native wake path can be established or verified in-session. Unmanaged shell-loop or cron-like workarounds that bypass first-party control-surface policy are forbidden.