---
title: "Agents and permissions"
description: "Define agent behavior, tool access, skills and subagents."
---

New projects use `beeuni_version: 2`. Agent behavior lives in `agents/<name>.md` (frontmatter and prompt); access grants live in `agents.<name>` in `beeuni.yaml`. The dashboard agent editor edits v2. Version 3 remains available for manually authored projects; its behavior lives in the manifest and the dashboard shows those agents read-only.

## v2: the default for new projects

```yaml
beeuni_version: 2
default_agent: assistant
agents:
  assistant:
    file: agents/assistant.md
    connectors: all
    secrets: all
    skills: all
    beeuni_permissions: all
```

## v3 reference (manually authored projects)

<a id="inline-agents-in-v3"></a>

## Example

```yaml
beeuni_version: 3
default_agent: assistant
skills:
  triage: skills/triage
agents:
  assistant:
    mode: primary
    prompt: Answer support questions and delegate order research.
    skills: [triage, beeuni-memory]
    subagents: [researcher]
    permission:
      bash:
        "*": ask
        "git status": allow
        "git diff *": allow
  researcher:
    mode: subagent
    prompt: Research the question. Never edit files.
    tools: [read, grep, web_search]
    permission:
      edit: deny
      bash: deny
```

<a id="what-an-agent-is"></a>

## Agent behavior

Behavior keys include `description`, `mode`, `model`, `variant`, `temperature`, `top_p`, `steps`, `options`, `color`, `hidden`, `enabled` and `permission`. `mode` is `primary`, `subagent` or `all` (default). `enabled: false` disables the agent. The default agent must be enabled and support primary sessions.

<a id="governance-is-deny-by-default"></a>
<a id="give-an-agent-access"></a>

<a id="ask-allow-or-deny"></a>

<a id="what-an-agent-may-do"></a>

## Grants and permissions

Omitted `skills`, `subagents`, `commands`, `extensions`, `connectors`, `secrets`, `apps` and `beeuni_permissions` grant nothing. Use `all`, `none` or a list of names. An omitted `tools` means every available tool; an omitted `permission` means `allow`.

`tools` controls which tools the model sees. `permission` controls whether a visible tool call runs (`allow`), waits for approval (`ask`) or is refused (`deny`). File and shell rules can match patterns. In v3, do not set `permission.skill` or `permission.task`: use `skills` and `subagents`.

Connector access, secret access and Beeuni project permissions are separate grants. An agent uses its own permissions, capped by its assigned role; starting it does not give it your role. Grants come from the default branch, so an agent cannot widen its access by editing its session branch.

<a id="agent-workspace"></a>

## Project repository access

Set `workspace: { project_repository: true }` on an agent that needs the project checkout. If omitted, this setting is `true` in manifest versions 1 and 2, and `false` in version 3. With `false`, new sessions have no project checkout or repository API access. Running sessions keep their initial setting. Tool, secret and connector grants remain separate.

<a id="skills"></a>
<a id="skills-give-an-agent-know-how"></a>

## Skills

A skill is a folder containing `SKILL.md`. Register the folder under `skills`; its final path segment and the frontmatter `name` must match the registry key. An unregistered project skill is not visible. The `beeuni-` prefix belongs to managed skills. Grant those by name, such as `beeuni-memory` or `beeuni-connectors`, or use `skills: all`.

```yaml
skills:
  triage: skills/triage
agents:
  assistant:
    skills: [triage, beeuni-memory]
```

<a id="commands"></a>

## Commands

A command is a saved prompt invoked as `/<name>`. Set exactly one of `prompt` and `prompt_file`. `$ARGUMENTS` inserts all arguments; `$1`, `$2`, and later placeholders insert positional arguments. Commands run on the selected agent and have no `agent` key. An agent that does not enable a command receives `403` with `command_not_enabled`.

```yaml
commands:
  summarize:
    description: Summarize a ticket.
    prompt: Summarize $ARGUMENTS in five bullets.
agents:
  assistant:
    commands: [summarize]
```

<a id="extensions"></a>

## Extensions

An extension registers an OpenCode plugin, a pi extension/package, or both. Enable it in each agent that needs it. Use a repository module for `opencode`; `pi` also accepts `npm:<package>@<exact-version>` or a source object with `extensions`, `skills`, `prompts` and `themes` filters. Version ranges and git sources are invalid. An omitted filter loads all; `[]` loads none. Extensions load when a session starts; switching agents keeps the initial extensions.

```yaml
extensions:
  audit:
    opencode: extensions/audit.opencode.ts
    pi: extensions/audit.pi.ts
agents:
  assistant:
    extensions: [audit]
```

<a id="which-agent-runs"></a>

<a id="how-a-session-picks-its-agent"></a>

## Subagents

Only declared agents run. A parent lists its allowed delegates under `subagents`; each delegate must have `mode: subagent` or `all`. Declaring an agent does not let every other agent call it. The built-in OpenCode agent names are disabled unless the manifest declares them.

Pass `agent_name` when creating a session to select a declared primary agent. If omitted, the session uses `default_agent`.

Merge configuration changes into the project’s default branch. New sessions use them, and running sessions pick up supported changes through configuration reload. A new agent cannot run before its declaration reaches the default branch. See [Runtime](/docs/work/runtime#config-convergence).

<a id="harnesses-opencode-and-pi"></a>

<a id="a-harness-runs-every-session"></a>

<a id="what-each-harness-supports"></a>

## Runtime

New sessions run pi. Existing OpenCode sessions remain supported. The manifest field `runtime` is deprecated and no longer selects a harness. V3 uses the manifest rather than repository harness folders. Put plugins and packages under `extensions`, and enable them per agent. `codemode: on | only | off` affects pi only.

<a id="legacy-versions"></a>

## Legacy versions

Version 1 (`beeuni.toml`) still runs and can be upgraded to v2 from Customize → Upgrades. Versions 2 and 3 require YAML. There is no automatic v2-to-v3 upgrade. Validate manually authored v3 changes before merging. See [Legacy TOML](/docs/project/legacy-toml).