Agents and permissions

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

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)

Example

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

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.

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.

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.

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.

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

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.

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

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.

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

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.

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.

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.