Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Agent Configuration

A hive agent is an AI worker. Hive keeps its coding-tool session alive, sends it a work prompt (a kick) on a schedule (a cadence), and watches for stalls, rate limits, and expired logins. Its configuration chooses the engine, model, and allowed behavior.

Start with a name, backend (the engine’s configuration ID), and model. A pin prevents automatic engine/model changes; beads are local work records; a lane groups matching work. tmux is the terminal-session manager Hive uses. ACMM selects a policy-level roster and human gates; configuration here does not replace the ACMM policy.

For labels that route or gate agent work, see Hive Labels and Control Signals.

The smallest agent that works

Before trying this, you need an operator account on a running hive, an installed and authenticated backend, and repository access configured for that hive. This example uses Copilot; importing YAML does not supply a subscription or log it in.

agents:
  scanner:
    backend: copilot
    model: claude-sonnet-4-6

For the portable agent definition YAML format, see ../AGENT-DEFINITION.md. For a complete portable AgentDefinition that exercises advanced display, channel, tool, and connection fields, see ../examples/agents/customized-agent.yaml.

That is a complete, valid agent. Defaults fill in the rest at load time:

  • enabled: true (unless you explicitly write enabled: false)
  • clear_on_kick: true — the session context is cleared before each kick
  • id and role default to the agent’s name (scanner)
  • bead_role: worker, beads_dir: /data/beads/scanner
  • Well-known names (scanner, ci-maintainer, architect, supervisor, sec-check, quality, guide, strategist, outreach, telemetry, operations) also get a default emoji, color, aliases, and lane keywords, so a bare scanner: entry already shows up in the dashboard as 🔍 with sensible triage keywords.

You almost never write a full roster by hand: applying an ACMM level (below) generates one for you, and the dashboard edits it live.

Where to put it and how to check it:

  • Existing hive: use the dashboard’s agent controls or import a portable definition. Do not paste this snake_case agents: entry into the portable import dialog; the formats differ. Do not overwrite an existing scanner entry to try the example.
  • New file-based deployment: merge the entry under agents: in the Hive configuration that deployment loads (--config/HIVE_CONFIG; container default /etc/hive/hive.yaml). Before starting it on real repositories, review its permissions and cadence; add enabled: false if you want to configure it before allowing startup.
  • Apply file changes through that deployment’s normal reload/restart process. Check the dashboard roster for the name and effective backend/model, then the agent session for successful login and the next kick. A saved entry alone does not establish a working backend. Use the dashboard to disable a trial agent afterward.

The ownership table below explains why editing a mounted seed may not change an already-running hive.

Next taskRead
Choose what it may doBehavior; permissions remain subject to the ACMM policy and hold gates
Change when it receives workCadences and the governor; pausing a cadence is not disabling an agent
Change its model or engineAtomic backend/model changes; update both together to avoid an invalid pairing
Understand a surprising work choiceExplain mode before changing permissions or removing gates
Keep a definition linked to its sourceLive-linked definitions; a linked refresh can replace definition-owned fields, but not operator lifecycle state

The formal-verification quality-lane opt-in (quality.formal) also lives in the dashboard under Settings -> Features.

In Go, agents: and the other runtime-owned blocks (backends, providers, tool_approval, agent_sandbox, turn, and the governor.{watchdog,litellm,vllm,llm-d,bob,trajectory,kick_limits,gateways,rotation,provider_budget} keys) are grouped under config.AgentRuntimeConfig / config.AgentRuntimeGovernorConfig in pkg/config/agent_config.go — the configuration surface of the Crux agent runtime (#13536). The grouping does not change where anything is written in hive.yaml; see Agent-runtime blocks.

Where configuration lives

Use the dashboard for settings you own. Hive saves them on persistent storage (a disk volume that survives container replacement). Do not edit /data/hive.yaml.runtime by hand. A seed is starting configuration, not necessarily the file that wins at the next boot.

Boot input: first boot versus restart

These are the container entrypoint paths; a directly launched binary uses the configuration path passed to it. A Kubernetes ConfigMap supplies seed text; a PVC supplies the persistent disk; an init container performs setup before Hive starts.

DeploymentNo persisted runtime file (first boot/reprovision)Runtime file already exists (later boot)
KubernetesThe init container seeds /etc/hive/hive.yaml from the ConfigMap. The entrypoint merges an existing /data/hive.yaml.dashboard over that seed, then writes /data/hive.yaml.runtime.The entrypoint boots from nonempty /data/hive.yaml.runtime (legacy hive.yaml.bak fallback). It does not re-merge the ConfigMap seed.
Docker, Podman, LXCThe mounted configuration seeds /data/hive.yaml.runtime.The entrypoint restores runtime configuration over the config path, or reads the runtime file directly when the mount is read-only. There is no Kubernetes dashboard-overlay boot merge.

During the Kubernetes seed-plus-overlay fallback only:

SettingWinner
Ordinary dashboard settingsOverlay over seed
acmm_levelOverlay when present; seed is a fallback, not an unconditional platform override
hub.is_publicSeed when set; the hosting hub can also reassert publication policy by heartbeat
GitHub App credentialsOverlay, except a real installed App in the seed is protected against a placeholder overlay wiping it

For example, changing acmm_level in the ConfigMap of a hive with a runtime file will not apply a new pack on restart. Use the dashboard’s pack controls or the hosting hub’s supported controls instead. Public-hosting policy remains the hosting administrator’s responsibility, not an arbitrary agent setting.

Saved settings and secrets

PathPurpose
/data/hive.yaml.dashboardDashboard changes on Kubernetes; an overlay means saved changes layered over starting configuration.
/data/agent-configs/<name>.yamlDashboard-managed, imported, and pack-generated per-agent entries, merged over the agent map at load time. Use dashboard controls rather than racing file synchronization.
/data/hive.yaml.runtimePersisted effective runtime configuration, rewritten by saves and used as a later boot input. Never hand-edit it.
/data/policies/agents/Kick templates and per-agent policy Markdown.

For environment overrides, ownership diagnostics, and detailed exceptions, see Spoke configuration layering. In particular, /etc/hive/config.env and per-agent overlays can affect the final loaded values after boot input selection.

  • Secrets never enter YAML. hive.yaml stores only env var names (api_key_env) and key file paths (api_key_file, governor.backup.key_file) — never key values. Values live in /data/secrets/ (dashboard-entered) or /secrets/ (Kubernetes Secret mounts). Because Config.Save() writes the whole config back to disk, a key value in YAML would be persisted in plaintext — so the code refuses the pattern entirely.

Anatomy of an agent

Every field below exists in the config schema today. Grouped by what it does:

Identity — how the agent appears

agents:
  scanner:
    display_name: scanner        # dashboard label (defaults to the YAML key)
    description: "Triages issues and opens PRs gated by `hold`."
    emoji: "🔍"                  # dashboard badge
    color: "#3498db"             # dashboard accent color
    role: scanner                # behavioral role; defaults to the agent name
    sort_order: 20               # dashboard ordering (supervisors default to 0, others 100)
    aliases: [sc]                # short names accepted in dispatch/commands
    bob:
      session_label: hive-scanner # bob backend only: overrides governor.bob.session_prefix + name

agents.<name>.bob.session_label gives a bob-backed agent a Bob session label without renaming the agent. If it is unset, governor.bob.session_prefix can prefix every bob agent (for example hive- makes scanner report as hive-scanner). Hive passes the label to Bob as --instance-id and exports it to the bob pane as HIVE_BOB_SESSION_LABEL; HIVE_AGENT, HIVE_AGENT_DISPLAY_NAME, tmux session, workdir, beads directory, claims, token buckets, and Hive token attribution stay keyed to the real agent name. Labels may contain up to 64 ASCII letters, digits, -, _, or . characters.

Renaming agents is a migration, not a display-only change. The YAML key is the agent identity: changing it splits tmux session/socket names, /data/agents/<name>, /data/logs/kicks/<name>, default /data/beads/<name>, claim holders, dashboard/token buckets, hub heartbeat names, and defaults that literally use the agent name. Prefer display_name for dashboard presentation and Bob session_label / session_prefix for Bobalytics tagging.

The legacy flat bob_display_name spelling is still accepted as an alias for older overlays, but new configs should use bob.session_label.

Engine — what powers it

    backend: copilot             # the method: claude | copilot | goose | codex | pi |
                                 #   bob | aider | omp | openhands | omnigent, or an inference backend:
                                 #   vllm | llm-d | litellm | watsonx | named gateway
    model: claude-sonnet-4-6     # model id for that method
    reasoning_effort: high       # reasoning effort, for methods that have one:
                                 #   codex (minimal|low|medium|high|xhigh, passed
                                 #   as -c model_reasoning_effort), agy
                                 #   (low|medium|high, passed as --effort), claude
                                 #   (low|medium|high|xhigh|max, passed as --effort),
                                 #   and omp (per selected model; passed as --thinking).
                                 #   Omit for the method's own default.
    cli_pinned: true             # pin the CLI so nothing auto-switches it
    launch_cmd: "/usr/bin/copilot --allow-all --model claude-sonnet-4-6"
                                 # explicit launch command (optional — hive builds
                                 #   one from backend + model + mode when omitted).
                                 #   Must launch the CLI named by `backend`; see
                                 #   "launch_cmd and backend" below.
    agent_spec: /data/agent-specs/reviewer
                                 # optional BYO-agent spec file or directory.
                                 #   When set, Hive loads agent.yaml/spec.yaml
                                 #   and applies its backend, model, mode,
                                 #   launch_cmd, prompt, tools, and skills at launch.

The dashboard API can update this field through POST /api/effort/{agent}/{effort}.

The dashboard shows a reasoning-effort dropdown next to the model picker for every method that has an effort control (codex, agy, claude, and omp). The value is validated at set time against the method’s own set, so a codex-only level such as minimal is refused for a claude agent rather than stored and dropped at launch. For omp, the dropdown is per selected model: Hive reads omp models --json and uses that model’s thinking levels, hiding the control for models that report no thinking support. Picking default clears the stored value; for claude and omp that means no effort flag at all and the CLI’s own default. The dropdown persists through the same path as the model picker (hive.yaml plus the per-agent overlay under agents_dir), which is the durable path on a hosted spoke: a hand edit of the agent’s file is reverted by the next sync, the dashboard write is not. Each dropdown change is recorded in the audit trail as set_reasoning_effort with the new value, like the other per-agent setting changes. The effort the agent was actually launched with is what the run rows and the - hive: PR trailer report, so a claude agent at xhigh shows effort=xhigh there and an agent with no stored effort shows none.

Claude setup-token

For backend: claude, an operator can use a long-lived token instead of the dashboard sign-in. Run claude setup-token interactively as the licensed operator and complete the prompts. The resulting token lasts about a year and is inference-only; it is not a general-purpose account credential. See Claude Code authentication.

Supply it to the Hive process as the secret HIVE_CLAUDE_OAUTH_TOKEN, or mount it in a secret file readable by Hive. Set HIVE_CLAUDE_OAUTH_TOKEN_FILE to that file’s path, or use the default /secrets/claude-oauth-token. The non-empty environment variable wins over the file. Do not put the token in hive.yaml, shell history, logs, issues, or agent panes.

Hive passes the token to Claude agents as CLAUDE_CODE_OAUTH_TOKEN at launch, even when a credentials file exists. It takes precedence over dashboard sign-in; signing in again on the dashboard does not replace it. Each agent retains its own Claude home and private state; sharing the token does not require sharing the whole home. Without an operator token, dashboard sign-in works as before.

To replace an expired or revoked token, run claude setup-token again, update the configured secret source, then recreate or restart Hive to load the new token and restart the affected Claude agents so their new sessions receive the replacement. Verify an agent completes a turn. See the backend auth recovery runbook.

Oh My Pi (omp) hub agents

backend: omp launches the OMP CLI as a first-class dashboard method. Hive gives each agent its own durable HOME under /data/home/agents/<name>, so ~/.omp/agent/agent.db can hold several provider sign-ins for that one agent (for example openai-codex for the primary model and anthropic for an advisor) without sharing refresh-token writers across agents. Select models with their provider prefix (provider/model). The dashboard model probe runs omp models --json and uses each model’s thinking list for the effort dropdown. At launch Hive passes --approval-mode ${HIVE_OMP_APPROVAL_MODE:-yolo}, --model <id>, and --thinking <effort> when set.

Omnigent (omnigent) agents

backend: omnigent launches the Omnigent CLI as an experimental T3 backend. Omnigent provides an open-source meta-harness layer orchestrating underlying agent engines (Claude Code, Codex, Cursor, Pi, and custom harnesses). On contributor local launches, Omnigent has no OS sandbox wired by Hive, so local mode refuses by default without HIVE_OMNIGENT_DANGEROUSLY_RUN_UNCONFINED=1. Container mode is the default and recommended boundary. Every launch is omnigent run --server local [--model <id>]: run opens the agent REPL (bare omnigent only starts a background server) and --server local pins a local Omnigent server, so remote-server mode is unsupported. Omnigent’s internal policy engine and sandbox evaluate additively, while Hive’s proxy remains authoritative on all repository writes. See backend-omnigent-cli-contract.md.

The dashboard also offers gemini as a live method (with live model discovery); as a persisted backend: value in hive.yaml, stick to the validated list above.

Reviewer independence

Reviewer agents can declare an ordered review_models pool so a PR is reviewed by a model independent from the one that authored it. The reviewer still receives one queue kick; each PR line carries review_with=<backend>/<model>, and the reviewer delegates that PR to an in-session Agent/task sub-agent with the listed model override:

agents:
  reviewer:
    backend: copilot
    model: claude-fable-5
    review_models:
      pool:
        - {backend: copilot, model: gpt-5.6-terra}
        - {backend: copilot, model: gemini-3.7-flash}
        - {backend: copilot, model: claude-opus-4-6}
      exclude_author_model: true
      exclude_author_family: false
      fallback: pinned

exclude_author_model defaults to true. exclude_author_family compares the normalized vendor prefix before the first dash (claude, gpt, gemini, grok, …). If no pool entry is eligible, fallback is pinned (use the agent’s configured model), skip (omit the PR from that kick), or requires_human (keep the PR visible with a human-review marker). Reviewers record the delegated sub-agent’s model as review_model in the verdict artifact, which feeds the author/reviewer model-pair metrics.

The same pool drives the review swarm (#13243). Each [review-perspective:…] kick (and the combined kick on non-fan-out hives) is planned against the PR’s author model — taken from pr.HiveModel, i.e. the — hive: trailer / agent_pr_created audit record — and the perspective prompt carries the same ## Independent review — run this review with <backend>/<model> section the queue kick’s PR lines do. Pool selection, exclude_author_model, exclude_author_family and fallback behave exactly as above; in the swarm skip withholds that perspective’s kick (reported in the dispatch plan’s skipped_review_models) and requires_human places a human hold on the PR instead of dispatching. Every perspective prompt also states the author model, and the planner stamps author_model and review_model (the pool choice, else the reviewer’s launch model) into the pending record so collected verdicts carry both even when no pool is configured.

review.perspective_models pins a model to one perspective, overriding the pool for that perspective only. The agent’s exclusions and fallback still apply, so a pinned model that matches the author family under exclude_author_family falls back like any other:

review:
  fan_out: true
  perspective_models:
    security: {backend: copilot, model: gpt-6-astra}
    correctness: {backend: copilot, model: gemini-4-argon}

The dashboard’s Evidence → Accuracy card and /api/evidence/summary add a per-author-family breakdown (outcomes_by_author_family, by_author_family, by_family_match) and each stored verdict carries author_model and same_family, so same-family vs cross-family accuracy is visible as soon as a pool is enabled.

BYO-agent specs

agent_spec wires ADR-0012’s bring-your-own-agent contract into the launcher. Point it at a YAML file, or at a directory containing agent.yaml, agent.yml, agent-spec.yaml, agent-spec.yml, spec.yaml, or spec.yml:

agents:
  reviewer:
    agent_spec: /data/agent-specs/reviewer
# /data/agent-specs/reviewer/agent.yaml
name: reviewer
backend: claude
model: claude-sonnet-4-6
mode: suggest
launch_cmd: /opt/reviewer/bin/reviewer --stdio
prompt: "Start with the external reviewer checklist."
tools:
  preset: advisory
skills:
  - review-checklist

At launch time Hive loads the spec with skillreg.LoadAgentSpec; the spec’s backend, model, mapped mode (observe → ADVISORY, suggest → ISSUES_AND_PRS, autonomous → ISSUES_PRS_MERGE), launch_cmd, prompt, tools, and skills become the agent’s effective launch configuration. If the spec omits launch_cmd, Hive still builds the backend command normally.

Behavior — what it may do, and when

    enabled: true                # default true; set false to keep it configured but off
    mode: ISSUES_AND_PRS         # GitHub interaction tier: ADVISORY | ISSUES_ONLY |
                                 #   ISSUES_AND_PRS | ISSUES_PRS_MERGE
    converse: true               # let this agent comment on issues/PRs and leave PR
                                 #   reviews, INDEPENDENTLY of mode. Off by default.
                                 #   See "Conversation is not a tier" below.
    bead_role: worker            # worker | supervisor (supervisors sort first,
                                 #   monitor the others); default worker
    kick_template: scanner-holdgated.md
                                 # named work-prompt template in the policies dir
    include_repos: true          # append the project repo list to each kick (default true).
                                 #   Prompt text only — it authorizes repos, it does
                                 #   NOT clone, mount, or provision anything on disk.
    repos: [console]             # WHICH repos this agent serves. Omit (the default) for
                                 #   the whole hive. Naming repos makes the agent a
                                 #   specialist: it is only handed work on these, its
                                 #   $HIVE_REPO/$HIVE_REPOS follow, and writes elsewhere
                                 #   are REFUSED by the proxy and the hive-open-pr /
                                 #   hive-merge / hive-open-issue relays — not merely
                                 #   discouraged. See docs/per-repo-agents.md.
    on_demand: false             # true = never kicked by the governor timer;
                                 #   only triggered explicitly (e.g. by you)
    continuous: false            # legacy shorthand: continuous in every
                                 #   non-quiet governor mode; prefer per-mode
                                 #   cadence: surge: continuous
    continuous_cooldown: 60s     # optional cool-down before that re-kick;
                                 #   default 60s, exponential backoff on
                                 #   undeliverable kicks
    continuous_budget_pct: 80    # optional token-budget guard; default 80%
                                 #   of governor.budget.total_tokens
    continuous_turn_ceiling: 45m # optional; if a kicked turn reports no end
                                 #   within this bound the governor presumes
                                 #   it over and re-arms; default 45m, -1 off
    clear_on_kick: true          # default true; false keeps session context across kicks
    stale_timeout: 28800         # seconds of silence before the agent counts as stale —
                                 #   must exceed its longest cadence
    busy_no_activity_threshold: 30m
                                 # surface Working/no-transcript activity after repeated
                                 #   undeliverable kicks; default 30m. At twice
                                 #   this silence the session is restarted (also
                                 #   when the live CLI pane shows no input prompt
                                 #   at all, or, on non-inference backends, sits
                                 #   on a consent/blocking menu); a
                                 #   kick_failed_repeatedly self-report is filed
                                 #   only if kicks still fail after that restart
    max_turn_duration: 0s        # optional visibility-only Working ceiling; 0 disables
    session_recycle:             # optional override of the fleet agents.session_recycle
      max_rss_mb: 1536           #   policy: recycle this agent's CLI session (a normal
      max_age: 6h                #   restart) once idle at the prompt and over the RSS
      min_idle: 2m               #   or age budget; enabled: false turns it off
    cli_memory:                  # optional override of the fleet agents.cli_memory
      auto_memory: false         #   policy: CLI auto-memory (Claude MEMORY.md, Codex
      clear_on_kick: false       #   memories, Copilot memory) off; wipe before each kick
      drain_to_knowledge: false  #   first turn each memory fact into a draft knowledge entry
      drain_on_write: false      #   and drain a Claude memory write at once (PostToolUse hook)
    restart_strategy: immediate  # how to bring a dead session back
    beads_dir: /data/beads/scanner   # work-record (bead) storage; default per-agent
    replicas: 3                  # materialize scanner, scanner-2, scanner-3 (max 5)
    lane_keywords: [bug, triage, fix]   # routes matching issues into this agent's lane
    detect_keywords: [scanner, triage]  # attributes GitHub activity back to this agent
    cadence_scope: per_repo      # aggregate (default) | per_repo — opt this agent into
                                 #   one governor timer PER WATCHED REPO instead of one
                                 #   hive-wide timer. Only effective when the hive-level
                                 #   governor.cadence_scope is also per_repo; see
                                 #   "Repo-scoped cadences" below.

Conversation is not a tier

mode is a ladder: each rung is a strict superset of the one below, from “observe only” up to “merge on green CI”. converse is not on that ladder. It grants exactly two things — posting a comment on an issue or PR, and leaving a PR review — and nothing else moves.

It exists because those two operations had nowhere sensible to sit (#4492). Commenting was bundled with ISSUES_ONLY, alongside creating issues, editing issue bodies and relabelling; leaving a PR review was bundled with ISSUES_AND_PRS, alongside pushing branches. Both bundles are wrong in both directions:

  • An ADVISORY agent that spots something on a thread could not reply. It could only emit a bead nobody outside the hive ever sees.
  • Letting it reply meant promoting it to ISSUES_ONLY, which also handed it the ability to rewrite issue bodies and relabel — and a reviewer who wanted comment-only had no way to ask for it.

With converse those are separable:

What you wantConfiguration
An agent that observes and can reply, but files and edits nothingmode: ADVISORY + converse: true
An agent that files issues but never speaks on a threadmode: ISSUES_ONLY (the default — converse is off)
A merge-capable agent that also reviews at ADVISORY-level trustnot expressible; reviews come with ISSUES_AND_PRS anyway

It only ever widens. converse is checked beside the mode tier, not instead of it, so an agent already at a tier that permits an operation keeps it. Turning converse on can never take anything away, and it cannot reach anything the tier ladder does not already gate: issue creation, editing, relabelling, pushing, opening a PR and merging all stay exactly where they were. The hard-denied routes (direct PR creation, direct merge) are unreachable by any capability at all.

It is off everywhere by default, at every ACMM level, so a hive that does not mention it behaves exactly as it did. The only way an agent starts talking is an operator writing converse: true.

Enforcement is the MITM proxy, over both REST and GraphQL — which matters, because gh issue comment and gh pr review send GraphQL, not REST. On the GraphQL side the grant is evaluated over the whole document: a mutation that comments and edits an issue, or comments and merges, is not conversation and is refused at the tier the non-conversational half requires.

For prompt file resolution and the complete built-in ${VAR} reference, see Policy and prompt templates.

Declarative extensions

Three optional blocks replace hardcoded behavior with declarations:

    channels:                    # how the agent gets triggered. Omit = governor timer.
      - type: kick               # kick is the only supported type (see below)
    tools:                       # tool permissions. Omit = the mode field governs.
      preset: issues-only        # advisory | issues-only | issues-prs | full
      rules:                     # per-tool allow/deny overrides on top of the preset
        - pattern: "mcp__github__create_issue"
          action: allow
          reason: "advisory issues are fine"
    connections:                 # external integrations
      - name: github-mcp
        type: mcp                # mcp | api | knowledge
        uri: "stdio:///usr/local/bin/mcp-github"

Presets map onto modes (advisory denies issue and PR creation, issues-only denies PRs, issues-prs and full deny nothing), and an explicit allow rule overrides a preset deny.

Replicated agents

Set replicas: N on a declared agent to run a small pool with the same prompt, backend, model, mode, channel, tool, and metadata settings. N defaults to 1 and is capped at 5; config load fails if it is outside 1..5. Hive materializes derived names as -2, -3, … (scanner, scanner-2, scanner-3). Do not declare those derived names yourself: a real scanner-2 entry collides with scanner: { replicas: 2 } and is rejected. Derived replicas get their own IDs and bead directories (/data/beads/scanner-2) but inherit the base agent’s kick template/prompt selection. Runtime-derived replicas are stripped before saving and recreated on the next load. For the reviewer lane, review.reviewers.autoscale can raise and lower the materialised count at runtime between min and max; the declared replicas then only seeds the initial size. See review-swarm.md.

Trigger channels

channels: declares how an agent is woken. If the block is omitted, governor timer kicks work as usual. kick is the only supported type; declaring it just makes the default explicit.

TypeRequired fieldsBehavior
kicknoneKeep ordinary governor timer kicks.

The former webhook, bead, schedule, and discord types were declarative-only: the trigger runtime meant to serve them (pkg/channels) was never wired into the binary and was removed (#5591). Declaring one of them used to validate cleanly and then silently suppress governor kicks, leaving the agent permanently dormant — config validation now rejects them instead.

Rounding out the schema — fields you will rarely touch:

FieldWhat it doesDefault
idStable identifieragent name
acmm_levelsACMM levels this agent participates inall
caveman_modePrompt-compression experiment: lite, full, ultra, wenyan; see belowempty (disabled)
jev_modeGive the agent the Jev typed-decision tool: off, assist; see belowempty (off — nothing installed, no Jev calls)
explain_modeAsk the agent to report why it made each tool call: off, brief, full; see belowinherit the hive default
metrics_collectorNamed metrics source for the stats panelnone
stats_displayCustom sidebar metrics (key, label, source, field, style, optional icon/target). The Diagnostics Quality stats card mirrors the quality agent’s configured entries. A pct/pct-bar stat with no measurement renders —, not 0%.none (an agent starts with no stats unless it is a built-in with defaults)
hidden (packs only)Keep a pack agent out of the default roster viewfalse

If a kick to an agent fails or an agent is flagged kick_refusal, see Kick refusals.

Explain mode (debugging agent behaviour)

Agents are told to act, not narrate. Every policy carries an “Output Rules — Terse Mode” block, and on inference backends the agent manager appends an explicit EXECUTE, DO NOT NARRATE instruction to each kick. That rule earns its keep — weak models otherwise answer a kick with a plan for someone else to run instead of running it — but it also means that when an agent does the wrong thing, there is nothing in the log saying why.

explain_mode buys that visibility back for one agent at a time, without relaxing the rule for anything else.

ModeWhat the agent is asked to addCost
offNothing. Identical to the behaviour before this option existed.none
briefOne EXPLAIN: line before each tool call, giving the reason for that specific call.small, per tool call
fullbrief, plus a closing EXPLAIN: block: the goal as understood, the approach chosen, alternatives rejected and why, and what evidence would have changed the decision.larger, per kick
agents:
  scanner:
    backend: claude
    explain_mode: brief

What it does and does not change

  • The agent still acts. The instruction states that tool execution remains the requirement and that a response containing only explanation is a failure. It is appended after the EXECUTE, DO NOT NARRATE block, so it reads as a qualification of that rule rather than a replacement for it.
  • Terse mode is suspended on EXPLAIN: lines only. A caveman-compressed explanation would be useless to the human reading it, but the agent’s real output — log lines, bead titles, PR descriptions — keeps whatever compression you configured.
  • It is per-kick, not a prompt edit. Nothing in src/policies/ or examples/*/agents/*.md changes, so toggling it does not alter any agent’s actual instructions and does not require a redeploy.

Reading the explanation

Explanation lands in the agent’s ordinary log, tagged with the EXPLAIN: prefix. Agent logs are tmux pane scrapes, so there is no second channel to write to — but the prefix makes the split a read-time choice:

URLShows
/api/agents/<name>/logThe log as always: work and explanation interleaved.
/api/agents/<name>/log?explain=onlyJust the reasoning.
/api/agents/<name>/log?explain=hideThe log as it would read with explanation off.

grep EXPLAIN: works the same way on a downloaded log.

Fleet-wide default

To turn explanation on everywhere without editing each agent, set the hive-wide default. It lives in governor config, so it is settable from the dashboard:

Dashboard — Settings → Governor → General → Default explain mode. The field also reports which mode is in force right now and where it came from, and takes effect on the next kick; no restart.

hive.yaml

governor:
  explain_mode: brief   # off | brief | full — omit for "no hive default"

Environment — HIVE_EXPLAIN_MODE=brief on the deployment still works, as the fallback consulted when governor.explain_mode is unset. Prefer the config field: the env var is set on the deployment, which a hosted hive’s owner has no access to.

governor.explain_modeHIVE_EXPLAIN_MODEHive default
unsetunsetoff
unsetfullfull
brieffullbrief — config wins
offfulloff — an explicit off in config is a choice, not “unset”

The per-agent field is a tri-state, and the difference matters:

explain_modeWith a hive default of fullMeaning
unsetfullInherit the hive default.
offoffExplicit opt-out; a fleet-wide default does not override it.
briefbriefExplicit per-agent choice wins.

An unrecognized value in any of these places resolves to off, so a typo degrades to the previous behaviour rather than to a mode nobody asked for. Hive injects the resolved mode into each agent process as HIVE_EXPLAIN_MODE, so an agent’s own skills and scripts can branch on it without re-deriving the precedence rules.

Leave it off outside of debugging: the explanation is extra output tokens on every kick.

Caveman prompt compression

caveman_mode installs the upstream JuliusBrussee/caveman skill/proxy for supported backends before an agent starts. It is optional and experimental; leave it empty for maximum output fidelity.

ModeDashboard descriptionWhen to use
liteRemoves filler while preserving normal language.Lowest-risk token reduction for routine agents.
fullConverts output toward terse “caveman-speak”.Use when cost matters and operators accept rougher prose.
ultraTelegraphic compression.High-volume lanes where compact summaries are more important than nuance.
wenyanClassical Chinese-style compression.Specialized/experimental mode; use only when readers and downstream tools can tolerate it.

Implementation notes:

  • Config validation accepts only lite, full, ultra, wenyan, or empty.
  • claude, copilot, and gemini are auto-wired before first message.
  • goose, codex, and aider get the skill installed and then receive /caveman <mode> after the CLI reaches an input prompt.
  • Unsupported backends log that caveman is not supported and continue without compression.
  • The UI describes the feature as roughly 65% output reduction, but exact savings vary by prompt, backend, and task.

Jev typed decisions (jev_mode)

jev_mode: assist gives an agent Jev (TypeSafe AI’s confidence-scored typed-decision model) as a tool, so quick yes/no, pick-one and rubric-score judgments — duplicate checks, “which of these N issues is relevant”, “does this diff touch secrets”, rubric scoring before posting a review, gating low-value actions — are answered by a cheap model billed on input tokens only instead of frontier-model reasoning. It is per agent and off by default, mirroring caveman_mode.

agents:
  scanner:
    jev_mode: assist      # off (default) | assist
 
jev:                       # hive-wide client; all optional
  provider: openrouter     # openrouter (default) | typesafe
  model: typesafe/jev-1.13 # default per provider (typesafe: jev-latest)
  endpoint: ""             # override the provider's systemone URL
  api_key_env: JEV_API_KEY # falls back to the connected OpenRouter gateway key
  timeout: 5s

Toggle it per agent from hive.yaml, the agent’s General settings panel (“Jev Mode”, next to Caveman Mode), or hivectl agent jev-mode-set &lt;agent&gt; assist. The dashboard select stays disabled with a hint until the hive can resolve a Jev key (JEV_API_KEY, or an OpenRouter gateway connected under Settings → Governor → Model Gateways). Because the skill and env are applied at launch, saving a change of jev_mode from the dashboard or hivectl restarts the agent (as a model or backend change does); editing hive.yaml by hand takes effect on the agent’s next start.

What turning it on does:

  • Skill. Before the CLI starts, the manager writes the embedded jev-decide SKILL.md into the agent’s CLI home (~/.claude/skills, $CODEX_HOME/skills, ~/.copilot/skills, ~/.gemini/skills, ~/.config/goose/skills), as the agent user. The skill tells the agent when Jev is the right tool and that it must never be used to generate code or prose. Backends without a known skills directory still get the CLI and env below.
  • Tool. hive jev decide --type choice|score|probability --question … [--option name[=description]]… [--level …]… [--state json] prints {"answer","confidence","probabilities","model","input_tokens"}. choice picks one of 2–32 options; score returns a position along 2–10 ordered rubric levels; probability returns P(yes) for a statement (TypeSafe’s Noul; confidence is derived as |2·P − 1| because the provider reports none for it).
  • Proxying. The CLI only ever talks to the hive’s loopback decision endpoint (127.0.0.1:18446). The hive identifies the caller from the socket UID only (the unforgeable half of the egress proxy’s check — the self-asserted Proxy-Authorization fallback the proxy allows under HIVE_PROXY_ADVISORY_OK is deliberately not honoured here), refuses any agent whose live jev_mode is not assist, attaches the Jev key, and forwards to the provider. Agents never see the key. Consequence: Jev requires per-agent UID isolation (the entrypoint’s uid-map.json); on a shared-UID or advisory-only deployment every call is refused as unidentified.
  • Budget and audit. Input tokens are recorded against the agent through the same inference token sink the governor budget reads, and every call is written to the audit log as jev_decision with question_type, confidence, input_tokens and model — never the question or state.
  • Env. HIVE_JEV_MODE=assist and HIVE_JEV_ENDPOINT are exported to the agent only when the mode is on.

Config validation accepts only off, assist, or empty; the dashboard and hivectl writes apply the same gate.

Methods: subscription CLIs vs self-hosted inference

backend: picks one of the CLI or inference families below. Hosted execution is a separate runs.external.<engine> binding and is never a backend: value: it has no local binary, CLI login, or live model discovery.

MethodFamilyAuthModel discovery
claudeCLIlog in once per methodmaintained list (Anthropic exposes no “list my models” API)
copilotCLIlog in once per method (GitHub device flow)live — entitlement-filtered /models on your plan’s API host
geminiCLIAPI key (GEMINI_API_KEY)live — Google models API, filtered to generateContent
gooseCLIprovider-configured (GOOSE_PROVIDER)curated per-provider list
vllminferenceendpoint + optional key — no loginlive — /v1/models
llm-dinferenceendpoint + optional key — no loginlive — /v1/models
litellminferenceendpoint + API key — no loginlive — /v1/models, entitlement-filtered per key
openrouter (gateway name)inferenceModel Gateway key or scan-to-fund flow — no CLI loginlive — OpenRouter /v1/models, plus curated fallback
claude-managed-agentshostedAPI key reference (api_key_env or /data/secrets api_key_file) — no CLI loginpinned agent/model version; no discovery

Two rules of thumb:

  • CLI methods are subscriptions. You log in once per method from the dashboard, and every agent using that method shares the login. For claude, sharing is not instantaneous: the OAuth token is shared immediately through the per-agent home bridge, while the session identity (~/.claude.json, which is what decides whether the CLI shows a login menu) is adopted from an already-signed-in agent the next time each other agent launches or is restarted. So on a fresh install, expect the remaining agents to clear their 🔑 badge on their next start rather than the moment you finish logging in.

  • Inference methods are endpoints. You configure a base URL and a key reference (env var name or key-file path — the value goes in /data/secrets/, never in YAML). Agents on vllm/llm-d/litellm launch the Claude CLI routed through hive’s inference translator, so there is no separate login.

    Only POST /v1/messages is translated into an OpenAI /v1/chat/completions call. The Claude CLI also talks to its Anthropic host for housekeeping — telemetry batches (/api/event_logging/...), error reports, POST /v1/messages/count_tokens — and none of that has a meaning to an OpenAI-compatible gateway; forwarding it used to cost a gateway 400 Missing required parameter: 'messages' per call, charged against the provider’s request rate limit (roughly two failures per real completion in practice). The translator and the MITM reroute now answer those locally: count_tokens returns a chars-based estimate, anything under /api/ returns {}, and any other path is a 404 in Anthropic error shape with a WARN log line naming the method and path, so a new CLI endpoint shows up in the hive log rather than as gateway noise. Inference-routed claude sessions are additionally launched with DISABLE_TELEMETRY=1, DISABLE_ERROR_REPORTING=1, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1, and CLAUDE_CODE_AUTO_MODE_SERVER=0; subscription sessions are not. The last one matters for Claude Code’s auto-mode classifier: the CLI otherwise asks the inference host for a server-side safety verdict (safeguards field in, safeguard_results out) that an OpenAI-compatible gateway can never return, then halts the session on an interactive “this session isn’t eligible because your requests go through 127.0.0.1:18444 … Enter to continue” notice. With the variable set the CLI runs its own classifier requests through the translator like any other call. Should the notice still appear (for example from a settings file that re-enables the server check), the lifetime prompt watcher presses Enter for it.

Per-agent homes: what is shared and what is private

Each per-UID agent runs with its own durable HOME under /data/home/agents/<name>. “One login authenticates the fleet” is implemented by bridging — symlinks from the per-agent home back to the same path under the shared /data/home — and the bridge list is deliberately narrow:

Path under the agent homeKindShared?Why
.config/, .codex/, .cache/whole directoryyescredential/config state only (gh hosts.yml, goose keys, codex auth) and tool caches; codex session state lives under a per-agent CODEX_HOME
.claude/.credentials.json, .claude/settings.jsonfileyesthe Claude OAuth token and the fleet-wide settings hive seeds
.claude/projects/, .claude/todos/, .claude/history.jsonlper-agentnotranscripts, todos, and Claude Code’s auto-memory (projects/-data-agents-<name>/memory/MEMORY.md, keyed by the agent’s cwd)
.gemini/antigravity-cli/, .gemini/settings.json, oauth_creds.json, google_accounts.json, installation_iddir / fileyesagy and Gemini CLI sign-in and settings
.gemini/GEMINI.md, .gemini/tmp/per-agentnoGemini’s saved memory and session checkpoints
.bob/settings.json, .bob/settings/file / diryesthe auth-method/provider pins hive asserts for every bob agent
.bob/tmp/, .bob/trustedFolders.jsonper-agentnochat recordings and folder trust
.copilot/config.jsonfileyesthe Copilot CLI token map
.copilot/session-state/per-agentnoCopilot CLI transcripts
.claude.json, .bash_history, .npm/, .local/, .gitconfigper-agentnocontended session identity, shell history, npm cache, XDG data/state, git identity

Before #17031 .claude, .gemini and .bob were bridged whole, so every agent’s CLI state sat in one tree that any agent could read and rewrite: the user-level ~/.claude/CLAUDE.md, history.jsonl and todos/ were a single shared copy, and each agent’s cwd-keyed auto-memory (projects/-data-agents-<name>/memory/MEMORY.md, per-agent by path) was writable by every other agent and persisted on the PVC forever. Provisioning now retires those whole-directory bridges on the next launch, keeps only the login/settings entries above, and never deletes or moves anything under /data/home: a pre-existing shared memory store is left in place and logged once (shared CLI home still holds a persistent memory store …) so you can review or drain it (#17033) before removing it by hand. The dashboard’s token/cost scanners (data.claude_sessions_dir, data.bob_sessions_dir, data.copilot_sessions_dir) walk the shared path and every /data/home/agents/*/… sibling, attributing each per-agent tree to its owner, so cost accounting does not regress. HIVE_SHARED_AGENT_HOME=1 restores the legacy single shared HOME for every agent (and with it the shared memory).

Claude Code saves a refreshed OAuth token (about every 8 hours) by writing a temp file in ~/.claude and renaming it over .credentials.json. A rename replaces a symlink rather than writing through it, so after the first refresh the agent is running on a private 0600 copy of the token, the refresh has rotated the grant the shared file still holds, and every other agent fails its own refresh. On per-UID hives this logged the whole fleet out about every 8 hours (#17039 follow-up).

Hive now treats the login as the one piece of .claude state that is shared, and publishes it back: at every agent launch, every HIVE_CLAUDE_CREDENTIAL_BRIDGE_INTERVAL (default 5s) from the credential watchdog, and right after a dashboard sign-in, it checks each claude agent’s ~/.claude/.credentials.json. When a regular file has replaced the link, hive reads it — directly, or as the agent’s own uid through the same su-exec seam that adopts .claude.json sessions, so an agent-owned 0600 file is no obstacle — and:

  • keeps whichever credential is newer and usable in the shared /data/home/.claude/.credentials.json: the agent’s copy wins only when it is complete (access token, refresh token, recorded expiresAt), usable, and expires later than the shared one, or the shared one is unusable. A failed refresh (empty tokens, expiresAt 0) never wins;
  • moves the private file aside to .credentials.json.stale-<UTC time> in the agent’s .claude (owner and mode unchanged) and, when the agent’s copy was promoted, preserves the old shared file beside the shared credential the same way. Nothing is deleted; remove the .stale-* files by hand once you no longer want them;
  • restores the symlink and records a claude_credential_rebridged audit entry (kept=agent|shared, never token material).

When the file cannot be read either way (a deployment without su-exec), nothing is moved or relinked, the agent keeps the token it already had, and one ERROR per agent and file version names the path. The one exception is a dashboard sign-in: a fresh shared login is newer than anything an unreadable private copy could hold, so that trigger moves the unreadable file aside unread and relinks the agent. Memory, transcripts and todos stay per agent throughout; only the credential file is published.

Every hive-side write to a shared login or CLI config (.claude/.credentials.json, .copilot/config.json, the durable Copilot token) goes through crux/sharedfile: a randomly named temporary beside the target, mode and owner set on the open descriptor, verified, then renamed into place, and only when the target is absent or a regular file inside a regular directory the server owns. Anything else at those paths is refused and logged once. The entrypoint’s root permission guard applies the same rule to the files it repairs, and the shared dot-dirs carry the sticky bit so a dev-owned entry cannot be replaced by another uid.

CLI auto-memory (agents.cli_memory)

Subscription CLIs keep their own long-lived “memory” next to the transcripts: Claude Code’s auto-memory (~/.claude/projects/-data-agents-<name>/memory/MEMORY.md), Codex memories ($CODEX_HOME/memories/), Copilot CLI’s memory setting, and Gemini’s ~/.gemini/GEMINI.md. Hive agents already get their durable context from beads, the knowledge store, and the kick prompt, so a hidden per-CLI notebook mostly accumulates stale one-off inferences (#17032). The agents.cli_memory block controls it fleet-wide, and each agent may override it with its own cli_memory: block:

agents:
  cli_memory:
    auto_memory: false         # default false: pin every CLI's auto-memory feature off
    clear_on_kick: false       # default false: true wipes this agent's memory stores before each kick
    drain_to_knowledge: false  # default false: true drains each memory fact into a draft knowledge entry first
    drain_on_write: false      # default false: true also drains a Claude memory write at once (needs drain_to_knowledge)
KeyDefaultEffect
auto_memoryfalseWhen false hive pins the vendor switch off at launch: Claude Code gets CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 in its environment (docs); Codex gets [features] memories = false merged into $CODEX_HOME/config.toml (docs); Copilot CLI gets "memory": false in its per-agent ~/.copilot/settings.json (copilot help config). true writes the opposite pin so an operator’s own setting is never silently shadowed. Gemini CLI has no equivalent switch.
clear_on_kickfalseBefore every non-resume kick (next to the /clear sent by clear_on_kick), remove this agent’s ~/.claude/projects/*/memory/, $CODEX_HOME/memories*/, and ~/.gemini/GEMINI.md. Only the per-agent home under /data/home/agents/<name> is touched; nothing under the shared /data/home is removed, and agents running with HIVE_SHARED_AGENT_HOME=1 or as uid 0 are skipped. Copilot memory is server-side and has no local store.

| drain_to_knowledge | false | Before every non-resume kick, and before clear_on_kick wipes anything, read this agent’s Claude ~/.claude/projects/*/memory/ (MEMORY.md plus topic files), Codex $CODEX_HOME/memories*/ and the ## Gemini Added Memories section of ~/.gemini/GEMINI.md, and write each bullet or paragraph as a draft entry in the bead-synth-wiki vault (knowledge.bead_synthesizer.vault_path, default /data/vaults/bead-synth-wiki) with source: cli-memory, agent: &lt;name&gt;, cli: <claude\|codex\|gemini> and, when the Claude project slug ends in one of the agent’s repos, repo: <org/repo>. Entries are deduplicated by a SHA-256 of the normalised text (memhash), so repeated drains and the same fact from several agents produce one entry, which gains an agent:&lt;name&gt; tag per draining agent; an entry an operator approved, deprecated or renamed is still a duplicate and keeps its state. A memory file whose facts did not all reach the vault (vault unwritable, 200-facts-per-drain cap) is copied to /data/knowledge/auto-memory-spool/&lt;agent&gt;/ before the wipe and retried on the next drain (#17056). Drafts never reach a kick until a human approves them (#17033). Needs the in-process crux runtime. | | drain_on_write | false | Needs drain_to_knowledge. For Claude Code, Hive always seeds a SessionEnd hook with drain_to_knowledge; this adds a PostToolUse hook on Write\|Edit\|MultiEdit that drains a memory file under ~/.claude/projects/*/memory/ as soon as it is written, for long-lived sessions. Both run hive memory-drain --cli claude --agent "$HIVE_AGENT", never fail the session, and are merged into the Claude settings Hive manages without touching your own hooks entries (#17210). |

Set auto_memory: true on a single agent to let it keep a private notebook while the rest of the fleet stays stateless between kicks. The knobs are independent: auto_memory: true with clear_on_kick: true gives a memory that lives for exactly one kick, and adding drain_to_knowledge: true is the “memory → beads” flow: the CLI may take notes during a turn, every note becomes a reviewable draft at the next kick, and the private store is then emptied. The log line per drain is cli-memory: drained N facts from <agent> into bead-synth-wiki (dupes K, spooled S).

Every Model Gateway (and the bob backend) also accepts an optional key_name — a human-chosen LABEL for the configured key, e.g. key_name: openrouter-prod-key. It is safe-to-show metadata, not a secret: the dashboard’s gateway row displays it as “Using key: <name>”, or “(unnamed)” when no label is set, so operators can tell keys apart without ever seeing the value. For gateway keys, the row and settings/status APIs also expose keySHA256, the lowercase SHA-256 of the exact effective key string Hive will inject through the inference proxy; this lets operators compare Hive with LiteLLM/OpenRouter key-hash displays without revealing the secret. Saving a replacement key refreshes live inference proxy routes for running agents, so the next kick uses the new key without an agent restart. See inference-backends.md for a full YAML example.

Where a gateway key file may live

api_key_file for governor.litellm and for every entry under governor.gateways is only ever read from the allowed secret dirs: /secrets (the Kubernetes Secret projection) and /data/secrets (the PVC dir the dashboard writes UI-entered keys to). Any other path is never read, a security gate that stops a config value from turning into an arbitrary file read. To use a Secret, mount it under one of those dirs, for example a volumeMount at /secrets/litellm_api_key, and point api_key_file at the file there.

  • Save. The dashboard and the config API reject an api_key_file outside those dirs with a 400 that lists the allowed dirs and says where to mount the Secret (#18533).
  • Boot. An existing hive.yaml with such a path still boots, because the path was already being ignored and the hive has been running on its fallback key. Boot logs a WARNING: line for each one naming the field, the path, the allowed dirs and the fix.
  • Runtime. When a configured path is skipped, the hive logs one WARN per path, configured api_key_file is outside the allowed secret dirs and was skipped, with skipped_path and effective_key_source (the source actually used: the Secret mount, the PVC copy, or an env var).
  • Dashboard and API. The LiteLLM section of GET /api/config/governor and each gateway row carry keySource (file:<path> or env:<NAME>), keySourceDescription (for example key from /secrets/litellm_api_key (configured path /secrets-cb/litellm_api_key not allowed)) and apiKeyFileAllowed; the LiteLLM section also lists allowedKeyFileDirs. None of them carries key material.

Key rotation without a restart

The agent inference proxy (127.0.0.1:18444) no longer keeps the key it resolved when an agent’s route was set (#18532). For litellm and named-gateway routes it re-checks the key file every few seconds, and re-reads it when the file’s symlink target, mtime or size changed (a Kubernetes Secret update swaps the ..data symlink). It also re-resolves fully every 30 seconds, so a newly created key file or a changed env var is noticed too. A rotated key therefore reaches the next request without a hive restart.

When the gateway answers 401, the proxy re-resolves the key once. If that yields a different key, it retries the request once with it, and counts an auth failure only when the retry is also rejected. An unchanged key is not retried. The inference backend auth failure WARN carries key_source (file:<path>, env:<NAME>, static for a route with a fixed credential such as a minted watsonx IAM token, or none) and key_changed_since_start (whether the key differs from the first key this process resolved for that backend). It never logs the key.

Claude Managed Agents hosted execution

Claude Managed Agents is an external hosted engine, not a backend: value. The prototype is linked only with extwork_claude_managed_agents and is selected under runs.external.claude_managed_agents. It requires a Claude self_hosted environment in the contributor-private spoke with forced-egress or proxy-only policy. The worker receives its environment key and per-session work secret; it never receives ANTHROPIC_API_KEY.

runs:
  external:
    claude_managed_agents:
      enabled: false
      mode: shadow                         # report-only is the dispatch posture
      endpoint: https://api.anthropic.com
      workflow_version: claude-managed/2026-04-01
      agent_id: agt_private
      agent_version: 1
      toolset_version: hive-tools/1
      environment_id: env_private
      environment_type: self_hosted
      network_policy: forced-egress
      api_key_env: ANTHROPIC_API_KEY       # reference only; never the value
      model: claude-sonnet-4-6
      state_dir: /data/extwork/claude-managed-agents
      daily_budget_cents: 2500             # hard USD 25/day maximum
      github_write_path: none

The adapter performs an authenticated GET /v1/environments/{id} before creating a session, pins the agent/toolset versions, sends the bounded prompt and repository workspace, and records span.model_request_end token events in data.metrics_dir. Event IDs are deduplicated across restarts. Session list_cost, active seconds, and web-search counts are kept in the durable managed-agents ledger; the session budget is the remaining daily cents. Set github_write_path to none or proxy for a report-only spoke. Any other value (a direct GitHub resource, vaulted secret, GitHub MCP path, or direct_github_write) is rejected when the adapter is built. endpoint must be https unless its host is loopback, because the vendor API key is sent on every request. The hosted worker has no GitHub path in this prototype; the POST /pulls and PUT /pulls/{n}/merge proxy denial tests from #14124 are not yet covered.

Kubernetes manifests for deploying inference backends (vllm Deployment, EPP RBAC, kustomization) are in deploy/inference/.

Agents can inspect peer panes with hive-panes [lines] when the deployment includes src/deploy/hive-panes.sh. It reads pluk JSONL logs from /var/run/pluk/logs, skips the calling agent named by HIVE_PROXY_AGENT, strips terminal escapes, and prints the last N raw-output lines for every other agent. Use it for situational awareness; it is read-only and does not attach to another agent’s tmux session. See Agent peer-awareness logging for the pluk log format, when it’s available, and its retention behavior.

Every discovery probe is best-effort: a failed or absent probe falls back to a current static list, so a model dropdown is never empty. Fallback entries are marked “unverified” in the UI.

An agent whose backend is a model gateway (OpenRouter, LiteLLM, vLLM, llm-d, watsonx or a custom OpenAI-compatible endpoint) does not use a CLI’s static list at all. It inherits the gateway’s live /v1/models list: the model dropdown, the Default Model picker and auto-heal all read what the gateway currently serves. The same holds for any CLI you point at a gateway, because its model is then whatever id the gateway accepts. Only the CLI-native backends (claude, copilot, codex, gemini, goose, agy, omp, bob, pi) ever fall back to a static list.

Static lists drift as vendors ship models, so two checks keep them honest:

  • TestStaticModelListsShape (in src/pkg/dashboard) fails a PR if any static list is empty or has duplicates, or if a first-paint copy in static/index.html disagrees with its Go list.
  • The weekly Static model list freshness workflow compares the lists with public, keyless sources. The OpenRouter catalog is used directly for the curated OpenRouter suggestions, and for Claude, Gemini and OpenAI ids mapped onto anthropic/, google/ and openai/. npm release versions of the CLIs are included as context. The workflow keeps one tracking issue (label static-model-freshness) up to date. Catalogs that need auth (Claude OAuth /v1/models, the Copilot SDK, the Codex app server, Kiro, agy, omp, goose, bob) are not compared; the CLIs are probed live at runtime instead.

Model pinning and auto-switching

Each agent shows a 📌 pin on its CLI and its model in the dashboard. The semantics are deliberately narrow — a model changes out from under you in exactly two cases:

  1. Unpinned + governor. The governor may auto-select a different model (budget, mode). A pin blocks this — and only this. Your own explicit switch always goes through; it simply retargets the pin to the new model, so the agent stays pinned.
  2. Discovery says the model is gone. When a genuine (non-fallback) discovery returns a model set that no longer contains an agent’s selected model — a key swap or endpoint change stripped the entitlement — the agent is switched to the first available model, with a toast. A static-fallback list never triggers this, and a model that is still present is never re-selected.

Pin a model when reproducibility matters more than the governor’s budget optimizations. Leave it unpinned when you want the hive to manage cost for you.

Disabling a backend spoke-wide

A top-level backends: block restricts which backends agents on this spoke may be placed on (#11310):

backends:
  allow: [claude, codex]   # empty or omitted = every backend is allowed
  deny: [copilot]          # deny wins over allow

Names compare case-insensitively; an empty backend: (the hive default) is always allowed. The list is enforced where placements are decided:

  • ACMM pack apply never places an agent on a disallowed backend. A pack agent whose pack backend is disallowed gets the first allowed allow entry instead (or the hive default when allow is empty), without the pack’s model, so the replacement backend uses its own default model. A pack-owned agent already on a now-disallowed backend is moved the same way on the next apply. Backends an operator explicitly chose (operator-owned) are left alone.
  • ACMM pack agents follow the hive’s inference gateway (#14678). When every backend you picked yourself (operator-owned — and any inference backend or gateway name with no backend_owner, e.g. one written straight into hive.yaml, since a pack never writes one) names the same inference backend or configured gateway, and more than half of the other enabled agents already run on it, a pack agent whose pack backend is a subscription CLI is placed on that gateway instead, with no model: so the gateway’s default model applies — or, when the gateway has no default model, with the model your agents on it run (from their model: or the model picked on their dashboard card; the most common one if they differ), so it never launches without a model. An agent the watchdog paused for crash-looping without a model is resumed once it gets one. This applies to agents a level creates and, on every apply (each restart), to existing agents whose backend is still pack-owned — so after an upgrade the L2 supervisor/brainstorm may move from copilot onto your LiteLLM gateway alongside the new reviewer. An operator-owned backend: or a legacy backend: without an owner is never moved, a hive with an operator-picked CLI agent or with only a minority of agents on a gateway is left as is, and a pack that itself names a gateway or whose backend the backends: list replaced is not redirected. If no operator model is available on a later apply, a model already written on a pack-placed gateway is retained until an operator model or gateway default becomes available. If no operator backend pick remains (for example after runtime overrides are lost), gateway placements retained on two or more pack-owned agents still count toward the hive’s gateway, so agents added at a later level follow it too (#16740). The same unanimity, majority, and backends: allowlist checks apply. A new operator backend pick takes precedence over retained placements, and a new operator model takes precedence over retained models. Runtime overrides remain separately stored in hive-state.json. When reconciliation changes a gateway-routed agent’s model, the log identifies the previous value as old_model and the replacement as gateway_model.
  • PUT /api/config/agent/{name}/models rejects a placement onto a disallowed backend with 400 and a message naming it.

Changing backend and model together: use the atomic endpoint

Three API routes can change an agent’s method or model. If you are changing both, use the single atomic one:

PUT /api/config/agent/{name}/models     {"backend": "codex", "model": "gpt-5-codex"}

The other two set one field each and are fine on their own — but using them in sequence to change both is a live footgun (#5698):

POST /api/switch/{agent}/{backend}      # then
POST /api/model/{agent}/{model}

There is no transaction across those two calls. If the second fails, times out, or is simply never made, the agent is left with the new backend and the old backend’s model — a pair like codex --model claude-opus-5 that cannot launch. The failure does not surface at set time; it surfaces later as a dead pane.

The three routes differ in ways that matter here:

switch + model (two calls)PUT .../models (one call)
Backend and model applied togetherno — separate requestsyes
Backend value validatedyesyes
Model value validatedyes, but see belownot yet — #5698 phase 2
Restarts the agentyes, once per callno — syncs into the live process config
Claims operator ownershipyesyes

Two consequences worth knowing:

  • Model validation does not save you here. POST /api/model/... checks the model against the agent’s current effective backend, and deliberately fails open when that backend’s model list cannot be enumerated (see validateModelForAgent). Codex is exactly such a backend, so switch to codex followed by model set to a Claude id is accepted. Reverse the order and the model is validated against the backend you are about to leave. Neither order gives you a checked pair.
  • The atomic route does not restart the agent. It persists the pair and syncs it into the live process config, so the running CLI keeps its current method until the agent next restarts. That is usually what you want for a scripted change — the two-call path pays for two restarts — but if you need the change to take effect now, restart the agent afterwards.

launch_cmd and backend

backend is the operator-owned field; launch_cmd is derived from it. The two must agree: a launch_cmd whose executable is a different agentic CLI than backend names (say backend: codex next to launch_cmd: /usr/bin/bob …) is rejected by config validation, because the agent would be launched as one CLI and health-checked as another. Hive enforces this on every path that can move the two apart:

  • Changing the backend clears a contradicting launch_cmd. POST /api/switch/{agent}/{backend}, PUT /api/config/agent/{name}/models with a backend, and an ACMM pack apply that moves an agent’s backend all drop a launch_cmd that launches the previous CLI, and log launch_cmd cleared on backend switch with the agent, the previous command and the new backend. The agent then launches on the new backend’s default command. A launch_cmd that already launches the new backend, or a wrapper script that does not name a CLI, is kept.
  • Saves refuse the contradiction. hive.yaml and per-agent overlay writes validate the pair and return an error (surfaced as a 400 and a dashboard alert) rather than persisting a config the next boot would reject.
  • Boot degrades instead of failing. If a hive still boots with the contradiction in its base config (written by a version before this check), the loader drops that agent’s launch_cmd, keeps backend, logs config: dropped launch_cmd that contradicts the agent's backend … at ERROR, and raises a dashboard alert per affected agent. The hive stays up; save the agent once from the dashboard (or fix the file) to clear the alert. A contradiction in a per-agent overlay is handled by the older rule: the overlay file is skipped and the agent falls back to its hive.yaml entry.

Cadences and the governor

Agents don’t schedule themselves. The governor evaluates the work queue every eval_interval_s (default 300s), computes a mode from queue depth — idle → quiet → busy → surge (default thresholds: quiet > 2, busy > 10, surge > 20 per watched repo; override with threshold:) — and kicks each agent on the cadence that mode assigns it:

governor:
  eval_interval_s: 300
  modes:
    busy:
      threshold: 16        # queue depth that activates this mode
      supervisor: 5m       # per-agent kick interval in this mode
      scanner: 15m
      reviewer:
        times: ["09:00", "17:00"]
        days: ["mon", "tue", "wed", "thu", "fri"]
        tz: America/New_York
      release:
        cron: "30 9 * * 1-5"
        tz: America/New_York
      ci-maintainer: 1h
      architect: pause     # "pause" stops kicks for this agent in this mode
  • Thresholds scale with repo count. The default thresholds above are per-repo bases, multiplied by len(project.repos) — so surge is 20 on a 1-repo hive and 780 on a 39-repo one, and the mode ladder means the same thing at any hive size. A threshold: you set yourself is used verbatim and never scaled. Tune the curve with governor.threshold_scaling (linear default, sqrt, none). See Governor mode thresholds, which also covers the ACMM-pack interaction.
  • Mutually exclusive modes. Each per-agent, per-mode cadence is either an interval (5m, 2h, pause) or a time-of-day schedule — never both. Config load and API writes reject mixed forms with a 400/error.
  • Time-of-day schedules. Use times: ["HH:MM"] with optional days (mon … sun) and a required IANA tz. The timezone is stored explicitly and displayed with the schedule; it does not float with the viewer.
  • Advanced cron. Power users can provide a constrained five-field cron expression plus tz. Hive evaluates these with robfig/cron and schedule-local timezone handling.
  • Governor-mode semantics. Time-of-day schedules fire at their exact wall-clock times. Governor mode only selects whether that mode’s schedule is active; quiet/busy/surge multipliers do not scale exact times. pause/off, paused agents, on-demand agents, non-kick channels, and budget gates still suppress kicks.
  • Downtime catch-up. If Hive was down at a scheduled time, restart/eval grants at most one catch-up kick when the missed occurrence is within the last 10 minutes. Older missed occurrences are skipped and the next future occurrence is used.
  • Per-agent, per-mode intervals. Anything Go’s duration parser accepts works (5m, 2h) for interval mode.
  • Pausing. The value pause (or paused) suspends an agent for that mode without disabling it.
  • On-demand agents (on_demand: true) are skipped by the governor timer entirely — they run only when explicitly triggered (brainstorm works this way).
  • Continuous agents take another work prompt after their current turn finishes and a cooldown expires. Configure this per mode in the dashboard’s Cadences form; see the settings and diagnostics below.
  • Budget. When the weekly token budget is exhausted, kicks are suppressed hive-wide (exempt agents excepted) until the period rolls over.

Set stale_timeout with your cadences in mind: an agent kicked every 4h with a 30-minute stale timeout will look dead between kicks. The shipped packs use “longest cadence × 2”.

Cadences are not the only way an agent gets kicked: the additive triggers: config key declares CEL rules that kick a named agent directly off a source-control event (issue opened, PR opened, a label applied, a comment posted), independent of the governor’s queue-depth cadence. See CEL-based agent triggers.

Continuous scheduling: configure and verify

Set the mode’s cadence to continuous (case-insensitive), for example agents.scanner.cadence.surge: continuous, with busy: 1h, quiet: 6h, and idle: off. No name, including scanner, receives special behavior. The legacy continuous: true shorthand enables continuous scheduling in every non-QUIET mode; prefer per-mode values for new configuration. An active cadence entry is still required in the current mode.

The manager waits for the CLI to return to its input prompt, records the turn end, and schedules the next kick at ended_at + continuous_cooldown (default 60s). Enabling continuous on an idle agent, including by entering a continuous mode, schedules the first kick after one cooldown. When a non-continuous mode is selected, pending continuous work is cleared; an agent configured continuous only in other modes reports continuousBlocked: "not_in_mode".

Check it: agent settings expose per-mode Continuous. The read-only Governor cadence table shows ∞ continuous. /api/status reports lastKickEnd, idleSince while waiting, and the per-agent continuousModes, continuousKicks, and continuousTokens counters.

The same safety gates still apply. Continuous never interrupts a busy turn and respects enabled: false, operator/fleet-breaker pause, mode pause/off (including QUIET pauses), on-demand, non-kick channels, token/provider holds, rate-limit/quota backoff, and upgrade/restart holds. Failed deliveries, such as “CLI did not reach input prompt,” use capped exponential backoff.

SettingDefaultOperational effect
continuous_cooldown60sWait after a completed turn before trying another kick.
continuous_turn_ceiling45m; -1 disablesIf the most recent kick has no reported outcome by this time, warn, record presumed-ended, increment presumedTurnEnds, and re-arm after the cooldown. Delivery still refuses to type into a Working pane, so this is not permission to interrupt a long turn.
continuous_budget_pct80At this percentage of governor.budget.total_tokens, stop only the continuous loop and resume normal cadence. Status reports continuousBlocked: "budget".
Scheduler timing and recovery reference

The run loop wakes at the cooldown time, bounded to one early evaluation per 30 seconds, rather than waiting for eval_interval_s / eval_interval_webhook_s. If evaluation skips the agent for a gate the governor does not track (dashboard pause, first-scan deferral, provider-budget gate, upgrade drain), that wake backs off 1m, 2m, … up to 15m until the schedule changes.

This avoids leaving a continuous reviewer idle until the next webhook-healthy spoke evaluation, which may be 15 minutes away. Turn-end detection is a terminal-pane heuristic. Missing that signal previously left an idle continuous agent with no further kicks until restart; the turn ceiling now bounds that failure. Re-arming schedules an attempt, not a bypass of delivery checks.

Repo-scoped cadences (cadence_scope)

By default the governor runs ONE mode for the whole hive: total queue pressure picks idle/quiet/busy/surge, and every agent gets one timer. On a many-repo hive that aggregate can mislead in both directions — one hot repo drags every repo’s agents into surge cadences, or a hot repo’s backlog is diluted below the (repo-count-scaled) thresholds by dozens of quiet repos. cadence_scope (#6932) lets the governor resolve a mode per repo instead:

governor:
  cadence_scope: per_repo   # aggregate (default) | per_repo
 
agents:
  scanner:
    cadence_scope: per_repo # per-agent opt-in — only agents that ask get split timers
  • Two switches, both required. governor.cadence_scope: per_repo turns on per-repo mode resolution; each agent still keeps its single aggregate timer unless it also sets cadence_scope: per_repo. Replicas inherit the base agent’s setting. Either value may be aggregate (or omitted) to keep the historical one-timer behavior.
  • Base thresholds, unscaled. In per-repo scope each repo’s own actionable queue depth (issues + PRs) is compared against the base thresholds — repo-count threshold scaling does not apply, because the comparison is already per-repo.
  • One timer per repo. An opted-in agent gets a cadence entry — and last-kick bookkeeping — per successfully scanned repo, keyed agent|repo. Repos in different modes kick the same agent at different intervals.
  • Live control. The owner-only GET/PUT /api/config/governor/cadence-scope routes read and set the hive-level scope at runtime; see the API reference.

ACMM levels: agent rosters as packs

You don’t have to design a roster. Hive ships six ACMM packs (see What is a pack?; level-1.yaml … level-6.yaml, embedded in the binary and forkable) that pair a curated agent roster with governor cadences and a merge policy:

LevelNamePosture
L1Inception (Assisted)inception: brainstorm + guide, everything conversational
L2Advisory (Instructed)advisory beads only; agents observe, humans act
L3Quality-Gated (Measured)quality opens issues and test PRs gated by literal hold; the rest stay advisory
L4Security-Aware (Adaptive)scanner/guide file issues; quality, ci-maintainer, and sec-check can open PRs gated by literal hold
L5Semi-Autonomous (Semi-Automated)issues and PRs; PRs are gated by literal hold; humans batch-approve
L6Autonomousauto-merge on green CI; no level hold, except cross-repo outreach PRs (target repo not managed by this hive) remain held

Applying a level reconciles the whole roster, not just the diff: missing agents are created (as overlay files in /data/agent-configs/), existing agents are merged — pack values fill blanks, but your explicit backend:, model:, and enabled: false always win — and the level’s kick_template, mode and on_demand are updated so the agent’s policy matches the level (an on_demand you toggled yourself in the agent’s settings dialog is operator-owned and left alone; leaving on-demand starts the agent, entering it stops it). One exception to “pack values fill blanks”: a backend: the pack itself wrote may be moved onto the hive’s inference gateway, as described under Disabling a backend spoke-wide (#14678). A failed agent doesn’t abort the rest; the level is only recorded as cleanly applied when every agent reconciled.

The L5 roster is the canonical worked example — thirteen agents, nine on the governor timer, three opt-in agents paused in every governor mode, plus one on demand:

AgentModeCadence (all governor modes)
supervisor 👑health monitor, sweepsADVISORY5m
scanner 🔍triage + fix PRsISSUES_AND_PRS4h
ci-maintainer 🔧CI + dependenciesISSUES_AND_PRS4h
quality 🧪test coverageISSUES_AND_PRS2h
guide 🧭documentationISSUES_AND_PRS4h
sec-check 🛡CVEs, vulnerabilitiesISSUES_AND_PRS4h
reviewer 🔬repo-grounded PR review; routes to a human, never mergesADVISORY30m
architect 🏗RFCs, refactorsISSUES_AND_PRS4h
strategist 🧠cross-agent coordinationISSUES_AND_PRS4h
telemetry 📡managed-project instrumentationISSUES_AND_PRSpaused
operations 🚨managed-project operational practiceISSUES_AND_PRSpaused
redteam 🎭measured attacks on hive defenses (red-team agent)ISSUES_AND_PRSpaused
brainstorm 💡ideationADVISORYon demand

At L5, every agent PR gets a hold label automatically. The system proposes; it does not merge autonomously.

The quality lane has an additional opt-in formal-verification capability at L5/L6. Set top-level quality.formal: true to let quality identify protocol-shaped subsystems and author Spin/Promela models, their executable property contract, and reporting-only CI. The setting is inert below L5 and does not turn modeling into a default for every repository. See Formal verification for the admission, artifact, reporting, and maintenance rules.

Telemetry and operations are L5/L6-only agents. They stay absent below L5 and remain paused at L5/L6 until an operator deliberately opts in. Their lane keywords are disjoint: telemetry owns instrumentation and observability terms, while operations owns health, SLO, runbook, incident, rollback, and alerting terms.

Configure that opt-in under Settings → Project Observability. This tab is for the managed project’s target stack; the Features tab separately controls Hive’s own OpenTelemetry export. Selecting platforms persists them under governor.project_observability — and nothing else. The tab does not enable either agent (#7261 removed its enable toggles): it shows a read-only status line per agent (the agent card’s Enabled flag plus its real per-mode cadences), and actually un-pausing an agent is done from Agents → Cadences (a conservative 24h per mode is a good starting point).

governor:
  project_observability:
    open_source: [opentelemetry, prometheus, grafana]
    kube_native: [servicemonitor]
    commercial: [honeycomb]
    references:
      honeycomb:
        endpoint_env: OTEL_EXPORTER_OTLP_ENDPOINT
        credential_secret: observability/honeycomb-key

Reference fields accept names only: an environment-variable name or a secret-name/key reference. Literal endpoints, tokens, and API keys are rejected. With no selected backend, the policies fail closed: agents may detect the existing stack and report recommendations, but may not add an exporter or new external data flow.

After an initial telemetry advisory run, platforms mentioned in its findings are preselected as suggestions in the tab. They remain unsaved until an operator reviews them and clicks Save; after that, the persisted declaration governs future telemetry and operations work.

Redteam is also L5/L6-only and paused until an operator opts in from Agents → Cadences. Unlike any other agent it also needs a repos: scope: without one it is refused every repository. See Red-team agent.

Live-linked agent definitions (definition_source)

An agent can be linked to a whole portable AgentDefinition YAML file living in a GitHub repo, so an edit to that file propagates into the agent’s config on the next reload or startup — no redeploy, no dashboard edit. This is the whole-agent analogue of promptTemplate/prompt-source live-linking (see Policy and prompt templates); both are implemented as graceful-fallback resolvers in src/pkg/promptsrc and src/pkg/defsrc respectively.

agents:
  scanner:
    backend: copilot
    model: claude-sonnet-4-6
    definition_source:
      type: github          # only "github" is supported; defaults to it when repo is set
      owner: my-org
      repo: agent-definitions
      path: scanner.yaml
      ref: main              # optional; branch/tag/SHA — omit for the default branch

definition_source is DefinitionSourceConfig (src/pkg/config/config.go:518), a field on AgentConfig (config.go:935). owner, repo, and path are required for the source to be considered set (IsSet(), config.go:544); ref is optional and falls back to the repo’s default branch. url is a fifth, informational-only field the dashboard import UI uses to round-trip the pasted github.com blob URL — it plays no part in fetching.

What it does

On startup and on every config reload, defsrc.ApplyToConfig (src/pkg/defsrc/defsrc.go:416) walks every agent that has definition_source set, fetches the file’s content from GitHub, and merges the parsed AgentDefinition’s operator-safe fields over the agent’s baked config in place. It is wired at two call sites in src/cmd/hive/main.go:

  • Startup, line 1363 — applied once before the first kick, so a repo edit made while the hive was down is already reflected.
  • Config reload, line 3299 — re-applied on every reload, before initAgentConfigDrivenSystems, so downstream systems see the merged config.

Both call sites build the same defsrc.Resolver (main.go:1356), gated by func(slug string) bool { return cfg.GitHubDefinitionAllowed(slug) } (main.go:1358).

What fields the live definition can change

mergeAllowedFields (defsrc.go:170) is an explicit allow-list, not a deny-list: only fields it names are copied from the fetched AgentDefinition onto the baked AgentConfig. A field not in this list — including any privilege- or security-relevant field added to AgentConfig later — is preserved from the baked config by construction; a new field is safe-by-default rather than accidentally live-sourced.

AgentDefinition field (YAML tag)Applied to AgentConfig field
metadata.displayNameDisplayName
metadata.descriptionDescription
metadata.emojiEmoji
metadata.colorColor
spec.backendBackend
spec.modelModel
spec.roleRole
spec.modeMode
spec.sortOrderSortOrder
spec.beadRoleBeadRole
spec.staleTimeoutStaleTimeout
spec.restartStrategyRestartStrategy
spec.clearOnKickClearOnKick
spec.includeReposIncludeRepos
spec.laneKeywordsLaneKeywords
spec.detectKeywordsDetectKeywords
spec.aliasesAliases
spec.cadencesCadences
spec.promptTemplateKickTemplate/prompt template
spec.channelsChannels
spec.toolsTools
spec.connectionsConnections

Two merge rules to know before you rely on this:

  • A blank field never clears a baked value. For most fields, an empty string or empty slice in the fetched definition is skipped, so a minimal definition can’t silently wipe presentation you set elsewhere. ClearOnKick and IncludeRepos are the deliberate exceptions — their zero value (false) is a legitimate setting, so the definition’s value is taken as authoritative whenever the source resolves live (defsrc.go:212-216).
  • Everything else on the agent is preserved untouched, explicitly including: Enabled/Paused/Managed (operator lifecycle state), ID, BeadsDir, MetricsCollector, ACMMLevels, OnDemand, CavemanMode, JevMode, and — critically — the definition_source/prompt_source pointers themselves. A live definition cannot re-point the agent at a different repo (ApplyToConfig re-asserts this at defsrc.go:437-440 even though the merge already excludes it). Nothing under the hive-level variables.security block is reachable either — it isn’t part of AgentConfig at all.

The trust boundary: allowlisted repos are seed-only

definition_source is gated by Config.GitHubDefinitionAllowed(slug) (config.go:4731), which simply delegates to Config.GitHubPromptAllowed(slug) (config.go:4711) — the same seed-only gate used by prompt_source. On the seed path, fetching requires both (the owner approval for managed repos is below):

variables:
  security:
    allow_github_prompt: true              # default false (deny)
    github_prompt_allowlist:
      - my-org/agent-definitions           # exact "owner/repo" slugs only

This is the property operators most need to understand before enabling the feature: variables.security is honored only from the trusted config seed. LoadWithDashboardOverlay never merges the dashboard overlay’s Variables block (config.go:4412, config.go:4483-4485), so:

  • A dashboard save cannot turn allow_github_prompt on if the seed has it off.
  • A dashboard save cannot add a repo slug to github_prompt_allowlist.
  • A compromised or malicious dashboard overlay can neither widen the set of readable repos nor repoint an agent’s definition_source at an arbitrary repo — only a seed edit (ConfigMap in Kubernetes, bind-mounted file under Docker, Podman or LXC) can do either.

An empty allowlist denies every repo even with allow_github_prompt: true — the allowlist is required, not merely advisory.

Owner approval for the hive’s own managed repos

The seed edit is still the only way to allow a repo outside the hive. For one of the hive’s own managed repos (an entry of project.repos, qualified with project.org), the hive owner can approve it from the dashboard instead of editing the volume (#18490):

  • Settings → Security → Prompt sources lists each managed repo and whether prompt_source / definition_source may read from it. Approve… opens a confirm that names the trust implication: anyone who can merge to that repo can change what the hive’s agents are told to do and how they are defined. Revoke removes the approval.
  • The API is GET /api/config/prompt-sources and PUT /api/config/prompt-sources/owner-repos with {"repo": "org/name", "allowed": true, "acknowledge_trust": true} ("allowed": false revokes). Both are owner-only: read, read-write and merger sessions get 403. A repo outside project.repos is refused with a 400, and an approval without acknowledge_trust: true is refused.
  • Each approval covers that one repo only. It does not need allow_github_prompt and does not turn it on, so nothing on github_prompt_allowlist starts loading because of it.
  • Approvals are stored in the running config as variables.security.owner_github_prompt_repos (repo, approved_by, approved_at), written by the dashboard Save to the PVC runtime config, so they survive a restart. Every change is audit-logged as config_prompt_source_repo.
  • The dashboard overlay still cannot approve a repo: its variables block is never merged, so only the owner endpoint (or a seed edit) writes the list.
  • An approval counts only while its repo is still in project.repos. Removing the repo from the hive lapses the approval; the Prompt sources panel shows it as inert until it is revoked.

Config.GitHubPromptAllowed(slug) (and GitHubDefinitionAllowed, which delegates to it) admits a repo when either the seed gate or an owner approval allows it, so every caller (prompt, definition and review-perspective resolvers) honors both paths without change.

review.perspectives_source (the live-linked review perspective set; see review-swarm.md) uses the same seed-only gate: the resolver is allowed to read a repo only when GitHubPromptAllowed permits it, it resolves at the same resolve points (startup and every reload), and it follows the same fallback shape as Resolve above (last-known-good, then the inline config).

Fetch failures never blank an agent

Resolve (defsrc.go:283) never propagates an error to the caller: a reload must proceed even when GitHub is unreachable. On any failure it falls back, in order:

  1. Denied (not allowlisted) — logs a warning, keeps the baked config, Source: "denied".
  2. No fetcher (token-mode boot without a GitHub App client) — uses the last-known-good cached document if one exists, else keeps baked, Source: "no-client".
  3. Fetch error (timeout, network, 404, etc.) — falls back to the last-known-good cached document if one exists, else keeps baked, Source: "error". Fetches are bounded to 8 seconds (defaultFetchTimeout, defsrc.go:47) so a hung GitHub call cannot stall a reload.
  4. Malformed document (bad YAML, wrong kind, missing metadata.name) — keeps baked, Source: "error". A document is cached for fallback only after it parses cleanly (defsrc.go:325-329), so a later failure never falls back to a corrupt document.

A fetched file is capped at 512 KiB (maxDefinitionBytes, defsrc.go:43); an oversized file is truncated (and likely then fails to parse) rather than consuming unbounded memory.

The per-agent prompt_source (a kick template fetched from GitHub by pkg/promptsrc) has a tighter, token-oriented cap and a stricter failure mode (#12130): 96 KiB by default (promptsrc.DefaultMaxPromptBytes, >2× the largest shipped template; HIVE_PROMPT_SOURCE_MAX_BYTES overrides), and a body over it is rejected whole, never truncated. The kick falls back to the last successfully fetched copy, then to the normal kick_template chain, with a logged warning naming the repo, path, size and cap; the dashboard’s save/bake flow fails with the same message instead of writing a cut-off policy. See operator-reference.md.

Validating a source before saving it

defsrc.FetchOnce (defsrc.go:372) does a single gated fetch — bypassing the resolver’s cache — and returns a parse error to the caller. This is what the dashboard’s import/“keep linked” flow uses to surface a bad owner/repo/path/document to the operator at save time, rather than only discovering the problem silently on the next reload.

Format reference

The fetched file must be a valid portable AgentDefinition: kind: AgentDefinition and a non-empty metadata.name are required (ParseDefinition, defsrc.go:138); everything else is optional. For the full schema and a worked example, see ../AGENT-DEFINITION.md and ../examples/agents/customized-agent.yaml.

Agents declared in a managed repo (.hive/agents/)

A managed repo can declare agents itself: each .hive/agents/<name>.yaml on its default branch is a portable AgentDefinition, and the hive picks it up without a hive config edit (#18491). Nothing a repo declares runs until an owner approves it.

Which repos are scanned. Every repo in project.repos (a bare name is qualified with project.org) that passes the repo-sourced prompt allowlist, Config.GitHubDefinitionAllowed, the same gate as definition_source and prompt_source: the seed allowlist or an owner approval of the repo (see Owner approval for the hive’s own managed repos). A repo off the allowlist is never read, and its existing entries are left as they were. Files are read through the hive’s GitHub App client, the same path the live definition resolver uses; with no App client, discovery is off.

When. Once at startup, then every 15 minutes (HIVE_REPO_AGENTS_INTERVAL, a Go duration, at least 1m), and on a push webhook to a repo’s default branch that touches .hive/agents/ (a push that lists 20 or more commits always rescans, since GitHub truncates the list). A repo holds at most 50 definition files; extras are ignored with a warning.

What an owner sees. Agents → Import → Declared in your repos in the config dialog lists each file with a status (GET /api/agents/discovered):

StatusMeaning
pendingParsed cleanly and waits for an owner.
invalidNot a valid AgentDefinition (or unreadable); the error is shown. Fix the file and the next scan makes it pending.
approvedRegistered as an agent.
rejectedAn owner declined it. It stays declined until the file is removed.
orphanedApproved, but the file was removed. The agent is paused, not deleted.

Approving (POST /api/agents/discovered/approve, owner only) re-reads the file through the allowlist gate and creates the agent exactly like a keep-linked import, with:

  • definition_source pointing at the file, with discovered: true;
  • prompt_source pointing at a sibling .hive/agents/<name>.md when the repo has one (otherwise a spec.promptTemplate is saved as the kick template, as an import does);
  • backend, model and mode from the owner, never from the file. They come from the approval request (backend defaults to copilot; model and mode stay unset unless given) and can be changed later in the agent’s settings. Tools start unset for the owner to grant.

Because discovered: true is set, every later reload re-applies the file’s other allow-listed fields (the table above) but keeps backend, model, mode and tools as the owner set them (defsrc.KeepOwnerControlledFields). A keep-linked import without that marker behaves as before.

Removing a file marks an approved entry orphaned and pauses its agent, recorded with trigger repo-agent-discovery. The agent and its config are kept: if the file comes back, the entry is tracked again, but the agent stays paused until an owner resumes it. Removing a pending, invalid or rejected file simply drops the entry. A failed directory listing never orphans anything.

Entries persist in /data/repo-agents.json (HIVE_REPO_AGENTS_STATE overrides the path). POST /api/agents/discovered/refresh rescans now; POST /api/agents/discovered/reject declines an entry.

Kick templates: what an agent is told to do

kick_template names a Markdown file resolved from the hive’s policies checkout (/data/policies/examples/hivecommons/agents/, or the directory your policies: config points at), falling back to the defaults embedded in the binary (src/pkg/policies/defaults/). It is the agent’s periodic work prompt: on every kick, the template is loaded, variables like ${ISSUE_LIST}, ${PR_LIST}, ${REVIEW_PERSPECTIVES}, ${AGENT_NAME}, ${PROJECT_ORG}, and ${KNOWLEDGE} are substituted, and the result is dispatched to the agent’s session. ${NEW_RELEASES} renders the upstream releases the release-feed watcher found for the agent and has not yet delivered (empty otherwise). The shared kick preamble always tells agents that the governor-supplied issue/PR lists are authoritative and that proxy-blocked gh pr list, gh issue list, and gh search discovery should not be used.

Resolution order: the agent’s explicit kick_template wins; otherwise the ACMM pack’s template for that agent at the current level; otherwise convention — /data/agents/<name>/CLAUDE.md, then <name>.md in the policies checkout, then the embedded default. Pack templates carry the level’s policy in their names — scanner-holdgated.md is scanner-at-L5; the same scanner at L6 gets scanner-automerge.md.

A kick_template that names a file which exists nowhere in that chain is a dangling template, and it is not silent (#7390): the hive logs config: kick_template does not resolve at boot and config kick_template not found; falling back on every kick — both naming the agent, the fallback the kick actually uses, and every path tried — the agent’s Prompt Template tab shows ⚠ template not found: <name> (falling back to …) instead of an empty editor and renders no repo link for a file the repo does not ship, and the General tab refuses to set a new name that does not resolve. Saving text in the Prompt Template tab creates /data/policies/<name>, which then resolves; clear kick_template to keep the fallback instead. The value must be a bare file name (scanner-holdgated.md), never a path — a path is rejected at config load and by the per-agent overlay guard. Agents whose prompts are built in Go rather than from a template (the review swarm’s [review-perspective:…] kicks) should carry no kick_template at all.

The reviewer lane’s template, and what an override cannot change

One agent reaches its template by role rather than by kick_template: an agent with role: reviewer runs the escalated-PR adjudication lane (#5480) and renders reviewer-lane.md. An operator enables that lane by adding a cadence agent with that role, under any name and with no kick_template, so the ordinary resolution order above never reaches it.

reviewer-lane.md resolves through the same paths as every other template, so the contract is editable — the operator-saved copy wins, then the policies checkout, then the embedded default. That matters because this contract governs an agent acting on PRs sitting in a human queue, so three decisions are deliberately not in the template and cannot be changed by editing it (#5617):

DecisionWhere it livesWhy
Is the lane awake?Go, before any template is readBelow ACMM L5 the lane is dormant: scheduled kicks are skipped (logged as dormant below ACMM 5), and a forced kick is a stand-down. An edited template must not be able to wake a lane on a low-trust hive.
Is there work?Go, before any template is readAn empty escalated queue means scheduled kicks are skipped (logged as nothing to adjudicate) and a forced kick is a stand-down with no repo-rotation instructions (#11045, #11046). A template must not be able to manufacture a contract with nothing to adjudicate.
May this agent close a PR?Go, rendered into ${REVIEWER_CLOSE_AUTHORITY}Closing is operator-only below ACMM L6. Whether an agent may close a human-queued PR is a trust decision, not wording.

So the worst an override can do is change the wording of a kick that was already going to be sent. The template-specific variables are ${REVIEWER_WORK_LIST}, ${REVIEWER_MAX_PRS}, ${REVIEWER_PASSED_LABEL}, ${REVIEWER_RECOMMEND_CLOSE_LABEL} and ${REVIEWER_CLOSE_AUTHORITY}, alongside the usual built-ins.

Do not confuse it with reviewer-queue.md, which belongs to the pack-defined reviewer agent in the L5/L6 packs: that agent wakes on a 30-minute cadence, works the open PR queue in advisory mode and routes requires_human / reject verdicts to a maintainer via the triage label itself. Because a kick_template shadows the role-based routing, that agent never reaches this lane; the L5/L6 packs therefore ship a separate template-less adjudicator agent (role: reviewer, mode: ISSUES_AND_PRS, 30-minute cadence) to work escalated PRs (#9477). Its work list covers every escalated hive PR the hub lists — the escalated rows of ci_failing plus the escalated list in ci-failing.json, which carries conflicted, green, and pending escalations that have no failing check.

Portable agents bundle everything — config plus a promptTemplate — in a single AgentDefinition YAML you can import from a URL in the dashboard. The reference schema is ../AGENT-DEFINITION.md, and a worked example lives at ../examples/agents/customized-agent.yaml.

Writing guide: how issues and PRs should read (project.writing_guide)

Every default template that files an issue or PR carries the variable ${WRITING_GUIDE} immediately before the body template it tells the agent to fill in (--body "## Finding …", --body "## Test Improvement …"). It expands to the text of project.writing_guide, wrapped in a short header that says who set it and that it governs how the body or review comment reads — wording, plainness, length, tone — not what the policy requires it to contain. The body template stays authoritative: every section, field and piece of evidence appears in the template’s order, and the guide never drops, renames or reorders a section. If the guide asks for a high-level summary, the agent writes it at the top, before the template’s first section, as an addition (#9747). That opening paragraph and the title are written for a newcomer who does not know the codebase — what the thing is, what the problem or change is, why it matters to a user, in plain words and with no unexplained internal names, paths or jargon; the technical detail follows unchanged in the template’s sections below (#9926). It is empty by default, and an empty guide renders nothing — a hive that never sets it gets byte-identical prompts.

Owners can edit the same value from the dashboard at Settings → Labels → Writing guide. The editor writes project.writing_guide through the same config-save path as the required-labels policy, so the change takes effect on the next kick, survives restart, and appears in the downloaded hive.yaml.

project:
  writing_guide: |
    A person who was not in your head will read this. Write for them.
    Open with two or three short sentences: what changed, why, and what
    to look at. Short sentences. One idea per bullet. Use the project's
    own words. Put evidence under a <details> block and keep it to about
    300 words outside that block.

Why a setting and not AGENTS.md (#7667): a style rule in a repo’s AGENTS.md reaches the agent as background knowledge, lower in the prompt than the policy’s own body template, and when the two disagree the agent follows the template. The variable puts the owner’s rule next to the template, which is the only position that changed anything when tried. The alternative — editing each template in the prompt editor — saves a full copy of that policy to /data/policies/ that then shadows every upstream update to it, per agent, for a style preference.

Where you will see it: the agent’s Prompt Template tab renders the guide where the kick will place it, so you can confirm the setting took. Prompts built in Go take the rendered guide as a parameter rather than expanding ${WRITING_GUIDE} themselves. That includes the contributor relay’s task prompt, since #8124, immediately before the instruction that tells the agent to open the PR. The guide travels with the assigning hive, so a relay subscribed to two hives gets each hive’s guide on that hive’s tasks; see contributor-relay.md. The review swarm also carries it in review prompts, so posted review comments use the same editorial voice as issue and PR bodies.

Hive-authored issue decision policy (project.agent_issue_decision_policy)

project.agent_issue_decision_policy controls what happens when Hive’s own agents try to park an issue with hive-open-issue --needs-decision or label … stage/045-needs-decision. The default is resolve: Hive-authored issues do not park for sequencing, naming, numbering, config-shape, scope, or “approach A vs B” engineering questions. The agent should pick the simplest additive, backward-compatible option and record the choice in the issue body as Decision taken by hive: …; the relay downgrades a park to stage/010-actionable and writes an audit entry only when the request positively classifies as an engineering question; text that matches neither a risk category nor an engineering term still parks (fail closed). Set escalate to preserve the older behavior where every Hive-authored decision request parks.

Parking remains for risk categories: security posture, data loss, irreversible or public-facing behaviour, governance/policy/licensing, spend, credentials/secrets/infra the hive cannot access (owner-only), or a question about a human’s intent that cannot be inferred. Parked issue bodies should include Risk: <category> so the maintainer can see why a person is needed. Human-origin issue filings are unaffected.

project:
  agent_issue_decision_policy: resolve  # resolve (default) or escalate

Reference repos: what agents may study (project.reference_repos)

Some hives produce a deliverable about another project — a CNCF TechDocs hive whose authorized repo is cncf/techdocs assesses hivecommons/docs, for example. Without configuration, the scanner reads such an item as out-of-scope or critical, and the proxy has no way to say “read this repo but do not work it”. project.reference_repos names those repos (#18015). A reference repo is never an authorized repo: it gets no queue, no ACMM evaluation and no work items, and it cannot also be in project.repos.

Each entry is either a string (owner/name, read-only) or a mapping {repo, write, write_token_file}. Bare names are rejected because a reference repo lives outside the project org. How writes to these repos work, and how they differ from the repos the hive manages, is in Writing to repos you do not manage below.

project:
  repos: [techdocs]
  reference_repos:
    - hivecommons/docs                               # read-only (default)
    - hivecommons/hivecommons.github.io
    - repo: hivecommons/hive
      write: [issues, prs]                           # opt-in tier
      # write_token_file: /data/secrets/hive-ref-pat # optional: a maintainer token instead of the bot or the owner's account
  remote_write_identity: bot                         # bot (default), bot_only or owner: whose name the writes carry
TierAgents mayProxy refuses
read-only (string form, or no write)git clone/fetch over HTTPS, GitHub REST/GraphQL GETs. Every request goes out without auth because the hive’s App token is removed, so a private reference repo is not readable.Every non-GET, with a 403 that names reference_repos.
issues, prs or issues+prs (write:)The reads above, plus only: open an issue (issues), push a topic branch and open a PR from it (prs: as the owner, through the owner’s fork; as the hive bot, to the repo itself), and comment on an issue or PR the hive itself opened.Merges, pushes to the default branch (of the repo or of the fork), labels, assignees, reviews, closing other people’s items, and anything on the fork other than a push. Each refusal is logged as reference_repo in the violations log, so retrying cannot succeed.

Writes on the opt-in tier use a credential valid for that repo, never the hive’s own installation token. Which identity that is follows project.remote_write_identity (Whose name the writes carry below): the hive’s GitHub App bot, only on a repo whose owner installed the App themselves, or the hive owner’s own GitHub account, connected once on the dashboard (Settings → Repos → Reference repos → Connect GitHub account, #18197), under which issues, PRs and comments appear exactly as if the owner had filed them. For a hand-written entry an operator may set write_token_file instead (a maintainer PAT on the hive host); a derived entry never reads it. A hand-written write-mode entry with neither refuses boot with exit code 22 and a message naming both cures. These are direct POSTs. The hive-open-issue/hive-open-pr relays only act on project.repos, so a lane under write_surface.enforce cannot write to a reference repo at all (GitHub write surface).

What agents see: every kick carries a 📚 REFERENCE REPOS block listing each repo with its tier ([reference · read-only], [reference · issues+prs], …). It tells agents that an authorized-repo item whose deliverables name a reference repo is in scope. Findings belong in the deliverable inside the authorized repo, unless the tier allows an issue or PR. When a prs-tier entry has a credential, the block also names the login the writes appear under and the fork-and-PR commands (#18198). On the dashboard, each reference repo is a minimal card with a reference · <tier> chip and, for a write entry, the account it writes as; no stats, ACMM level or work items. Reference repos come in a separate payload field, so no queue or ACMM consumer counts them. Field-by-field defaults are in the operator reference.

Reference repos derived from an accepted request

Hand-writing reference_repos does not scale when the hive’s work arrives as requests. A TechDocs hive receives one assessment request per project, and each request names the repositories it is about. The hive therefore derives write-tier entries from an accepted request issue (#18139). Nothing in this flow needs the operator to edit the config.

The flow:

  1. A request issue is opened in an authorized repo (cncf/techdocs#395, say) through an issue form. Its body carries the form headings and the repositories under them.
  2. The workflow model bound to that repo declares which headings matter: spec.intake.referenceRepoFields lists the headings whose repositories are in scope and spec.intake.outOfScopeFields the headings whose repositories are excluded. A model without intake.referenceRepoFields derives nothing. For TechDocs that is cncf-techdocs-assessment@curated-2026.11.2; curated-2026.11.1 is unchanged, so a hive bound to it must rebind.
  3. A person with write access to the authorized repo applies triage/accepted. That label is the grant. The hive reads who applied it from the issue timeline and checks their repository permission. A label applied by a bot or App account grants nothing, so the hive can never grant itself access by moving the label. A label applied by someone without write access grants nothing either.
  4. Every repository under an in-scope heading, and not under an out-of-scope heading, becomes a write: [issues, prs] entry. The issue’s own repo, any authorized repo and any repo in project.repos are skipped.
  5. The credential follows project.remote_write_identity, exactly as for a hand-written write-tier entry: the hive’s App bot where the requesting project installed the App, otherwise (unless the setting is bot_only) the hive owner’s connected GitHub account. When neither applies, the entry is served read-only instead, the hive keeps running, and the request issue gets exactly one comment marked <!-- hive:reference-repos-read-only repos=... state=read-only --> saying which repos the hive can read but not write and, unless the setting is bot_only, that the hive owner connects their account on the dashboard to change that; the policies flip without a restart. The comment never asks the project to install the App. The comment is posted once per request issue and repo set, never again on a plain reload. A derived entry never consults write_token_file and never fails boot.

Lifecycle: the hive derives at boot, on every config reload and every HIVE_REFERENCE_REPOS_DERIVE_INTERVAL (default 10m, Go duration, see env-vars.md). Closing the request issue or removing triage/accepted drops the entry, its proxy policy and its kick line on the next pass. A hand-written entry for the same repo always wins over the derived one. Derived entries live in memory only: a saved overlay or runtime config never contains one, and a restart rebuilds them from the open issues. The same repo named by two accepted issues keeps the first and logs the second.

Writing to repos you do not manage (the two lanes)

The hive manages issues and PRs in two different ways depending on whether it is linked to the repository (#18196):

Linked repos (project.repos)Remote repos (project.reference_repos at a write tier)
IdentityThe hive’s GitHub App installationPer project.remote_write_identity: the hive’s App bot where the project installed the App itself (bot, the default, and bot_only), else the hive owner’s own GitHub account, connected once in Settings
What the hive doesFull management: backlog scan, queue, kicks, stage engine, labels, reviews, mergesParticipation only, whichever identity: open issues, open PRs (as the owner through the owner’s fork, as the bot from a topic branch on the repo), comment on and push to its own items
Follow-upWebhooks and enumerationA poll of the items the owner login opened that carry a hive marker; new comments and reviews go to the agent that opened the item
ProxyACMM rulesThe reference-repo gate: labels, reviews, assignees, closing others’ items, merges and default-branch pushes are always refused
The hubNot involvedNot involved; the hub never holds the token and its login scope is unchanged

Connecting the account. Settings → Repos → Reference repos shows the identity in use. Connect GitHub account runs a GitHub device flow with the hive’s own OAuth client asking for the public_repo scope: open the URL, enter the code, done. The token is stored on the spoke only, as an owner-only file under /data/secrets (HIVE_GITHUB_OWNER_TOKEN_FILE overrides), never in hive.yaml and never sent to the hub. It is re-checked every ten minutes; a revoked token drops every write-tier entry to read-only and Settings asks for a reconnect. Disconnect removes it from the hive; revoking it on GitHub is done under Settings → Applications on github.com. public_repo covers public repositories only: a private remote repo would need the repo scope and is not supported.

Whose name the writes carry (project.remote_write_identity)

An issue or PR posted under the owner’s own account reads as if the owner did the work, when they only commissioned it. project.remote_write_identity lets each hive choose (#18516). In Settings → Repos → Reference repos it is the owner-only control Post on other projects as:, with the choices Hive bot, falling back to me, Hive bot only and Me. Every change is audit-logged as config_remote_write_identity.

ValueOn a granted repo whose owner installed the hive’s GitHub AppEverywhere else
bot (default; a missing key is bot)Posts as the App bot (hivecommons-hive[bot] on the public fleet)Posts as the owner’s connected account; read-only if none is connected
bot_onlyPosts as the App botRead-only. The owner’s token is never used, even when it is connected
ownerPosts as the owner’s connected accountPosts as the owner’s connected account (the behaviour before this setting)

How it works and what it never does:

  • The grant stays the same. The setting only picks the name on writes the grant already allows. A repo gets a credential only when it is a write-tier entry, either hand-written or derived from an accepted request. An App installation by itself is never a grant. The hivecommons org, for example, installs the App for every repository and every hive, but a hive without an entry for one of those repos has no policy for it, so no token is ever minted for it.
  • Detection only. The hive asks GitHub, with the App’s JWT, whether an installation covers that exact repository (GET /repos/{owner}/{repo}/installation, cached for five minutes). Nothing in the hive asks a project to install the App: not Settings, not the kick, not the read-only notice.
  • One repo, minimum permissions. The bot token is minted on that installation, scoped to that one repository. It gets metadata: read always, issues: write for the issues tier, and contents: write plus pull_requests: write for the prs tier. It is cached until shortly before it expires and is only injected by the proxy’s reference-repo path for that repository. It never comes from the hive’s own installation and never carries linked-repo management.
  • The same gate. Labels, assignees, reviews, closing other people’s items, merges, default-branch pushes, scanning and kicks stay refused for every identity. The App owns no fork, so as the bot a PR’s topic branch is pushed to the reference repo itself, under the same default-branch guard. The kick gives agents the right flow for each repo.
  • No silent switch. If the App lookup fails transiently, the entry is read-only for that pass (credential_state: unresolved) and the hive retries on the next pass. It never falls back to the owner’s name. write_token_file on a hand-written entry still wins over every value.
  • Per-repo status. Settings shows, on each write entry, which identity will actually post and why: posts as hivecommons-hive[bot]: App installed on <org>, posts as <owner>: App not installed on <org>, read-only: connect your GitHub account, or read-only: bot only, App not installed on <org>. A change that would leave a hand-written write entry without a credential is refused before it is saved, with the error boot would stop on.
  • Upgrade. Hives that never set the key read as bot. Where the App is not installed, nothing changes. A granted repo whose owner installed the App now gets posts as the bot instead of the owner. Choose Me to keep the previous behaviour everywhere.

The own-item follow-up below follows the items opened under either identity, each repo read with its own credential.

Fork-and-PR. The owner’s account cannot push to a repository it does not own, so a PR against a remote repo goes through the owner’s fork: gh repo fork <owner>/<name> --clone=false, push the topic branch to https://<host>/<login>/<name>, then gh pr create --repo <owner>/<name> --head <login>:<branch>. The proxy allows exactly that (fork creation, pushes to the fork with its default branch protected, the PR against the remote) and refuses everything else on the fork. The kick spells the commands out, so git push and gh pr create need no agent-side special casing.

Own-item follow-up. Remote repos send no webhooks and are not enumerated, so the hive polls them: it lists the open issues and PRs created by the login each repo writes as (the owner’s, or the App bot’s on a repo that writes as the bot, #18516), reading each repo under its own reference-repo credential, keeps the ones whose body carries a hive marker (the — hive: attribution trailer or the 🐝 **Hive Agent** footer), fetches new comments, review comments and reviews, and delivers them to the agent the marker names, into its live session or as a 🌐 REMOTE ITEM FOLLOW-UP section on its next kick. State is in /data/turn/remote-items.json (HIVE_REMOTE_ITEMS_FILE overrides). Nothing else happens on the remote: no backlog scan, no queue, no stage engine (#18199).

What agents see: the 📚 REFERENCE REPOS block appends (from owner/repo#N) to each derived line, (from owner/repo#N; read-only: <reason>) when the credential fell back, and (read-only this pass: <reason>) while an App lookup is unresolved. The proxy rules are the ones in the table above: a derived entry unlocks opening issues and PRs on that repo and nothing else, and the read-only fallback unlocks nothing. On the dashboard, Settings shows derived entries read-only with a link to the request issue and the credential state, and the API answers an edit of one with 409.

Label policy: which issues agents may work

There is exactly one label-policy surface for the hive’s own agents — the Governor Configuration → Labels tab — and it has two polarities:

PolarityConfigMeaning
Exempt (deny-list)governor.labels.exempt (+ permanent hold/on-hold/hold/review, do-not-merge)“Never touch issues labeled with these.” Everything else is eligible. This has always existed.
Required (allow-list)project.issue_filter.require_labels“Only touch issues labeled with these.” Empty = every issue is eligible. This is what “only work approved issues” means.

By default a hive treats every open issue in its repos as candidate work. Projects that gate automation on a maintainer’s explicit approval label want the require polarity: a maintainer reviews an issue, applies the approval/queue label, and only then may agents touch it. (A fleet running against a busy upstream repo hit exactly this — the hive opened a PR for an issue the owner had not yet labeled for agent work; an exempt list cannot express that policy, because it can only name what to avoid, not demand a label be present.)

project:
  org: my-org
  repos: [my-org/common]
  issue_filter:
    require_labels: [approved-for-agents]   # agents may ONLY work these issues

Semantics:

  • Absent/empty require_labels = no gate — existing hives are unchanged; there is no default-on filtering.
  • An issue must carry at least one required label to be eligible. Matching is case-insensitive and exact (a prefix like approved-for-agents-maybe does not satisfy approved-for-agents — prefix matching would over-admit through an approval gate).
  • Exempt wins on conflict: an issue carrying both an exempt label and a required label stays excluded. There is deliberately no separate exclude_labels field — the exempt list is the exclusion mechanism, applied first.
  • PRs and the Hold list are unaffected: open PRs are in-flight work, and held issues still appear under On Hold.
  • PRs have their own, separate allow-list for reviews: review.require_labels (Settings → Features → Review Gate → “Only review labelled PRs”) keeps the hive from reviewing a PR until it carries an approval label; see review-swarm.md. Use a distinct label from the issue gate if the two approvals mean different things to your maintainers.

Both polarities are enforced at enumeration — the point where GitHub issues become the hive’s actionable set — not in the prompt. A filtered issue never enters the queue, never appears in a kick, never triggers plan-from-label, and cannot be re-selected by a confused (or prompt-injected) agent re-listing the repo. Kick prompts additionally state the active require policy so agents know the list is intentionally short. Both lists are edited on the Labels tab; an active require gate is also noted read-only under Projects, and hub-managed hives can receive issue_filter with their project config over the heartbeat.

Reporter trust: who filed it, not only what it is labelled

The two polarities above look only at labels, so a maintainer’s issue and a first-time stranger’s issue are admitted by the same rule — and at ACMM L6 a stranger’s request can be worked and merged on green CI with nobody looking. The require polarity fixes that only by making everyone, maintainers included, hand-label their own issues first. Reporter trust (#9665) splits the two:

project:
  issue_filter:
    reporter_trust:
      enabled: true                                  # off by default — existing hives change nothing
      trusted_associations: [OWNER, MEMBER, COLLABORATOR]   # the default; CONTRIBUTOR is deliberately not in it
      trusted_logins: [external-maintainer]          # trusted whatever GitHub says about them
      untrusted_require_labels: [triage/accepted]    # the default
      awaiting_label: needs-triage                   # default; set "" to skip the visible wait label
      comment: true                                  # default; posts one marked wait explanation
github:
  reporter_trust_hold: true                          # optional; nil follows reporter_trust.enabled
  • Admission. GitHub reports an author_association on every issue. A reporter in trusted_associations (or whose login is in trusted_logins) has their issues admitted by the ordinary rules. Anyone else’s issue is not actionable until a maintainer adds one of untrusted_require_labels. On the first excluded enumeration, the core github.Client.fetchIssues poller posts one <!-- hive:reporter-trust-wait ... --> comment explaining the gate and applies awaiting_label (default needs-triage) so the wait is visible; later scans do not repeat the comment. This is a poller-side write, not an agent prompt, and is capped at 10 new notices per poll. Once a maintainer adds the required label, the same poll loop removes the awaiting label only if that marker records that Hive added it, then admits the issue. This runs after the hold/exempt checks and before require_labels, so the ordinary allow-list still applies to trusted reporters afterwards — “everyone needs an approval label” stays expressible exactly as before. Hive- and bot-filed issues are not judged here; the #5117 self-authorization gate owns those on the PR side. An unknown reporter (no login, or no association in the payload) is treated as untrusted.
  • Merge. A PR whose rationale (its closing or referencing links, or the request’s declared issue list) traces to an untrusted reporter’s issue without any untrusted_require_labels acceptance label receives hold at every ACMM level, including L6, together with a marked notice naming the issue reporter (not the PR author). Any one unaccepted untrusted citation holds. A configured acceptance label supplies maintainer sign-off, so accepted issues do not trigger a new reporter-trust PR hold. A human removes the label; Hive never auto-releases a reporter-trust hold — the level-hold release path recognises the notice and leaves the label, and holdguard re-holds on a new head SHA. github.reporter_trust_hold follows reporter_trust.enabled unless set explicitly; project.repo_policies[].reporter_trust_hold overrides per repo; HIVE_REPORTER_TRUST_HOLD locks it from the environment, exactly like the #5117 knobs.
  • Where you see it. Both halves are edited in the dashboard: Settings → Labels → Reporter trust (the switch, the association checkboxes, extra logins, triage labels) and Settings → Repos (the hold, with the same all-repos default / per-repo override / inherit rows as #5117). An active gate is stated in the read-only note under Projects, and each repo card counts issues needs triage separately from generic filter refusals. The issue itself carries needs-triage while waiting when Hive had to add it. Holds carry the reason in the PR notice and in the agent_pr_created audit entry (reporter_trust_held, reporter_login, reporter_association).

Notification mode: how much of the hive’s bookkeeping becomes email

github:
  notifications:
    mode: quiet                                      # default; "normal" posts every note as its own comment/review

Every issue comment and every review the hive posts emails the PR author and every watcher of the repository; editing an existing comment notifies nobody. In quiet mode (the default) the hive’s own PR notes — stage stalled/regressed, the trusted-human 071 note, the duplicate-PR redirect — are sections of one <!-- hive:status --> comment per PR that is created once and edited afterwards; a “Reviewed — no findings” review is recorded as a verdict without a GitHub review and a head carries at most one hive review; the 071 note @-mentions the author once per cause rather than once per head. Nothing is lost: the Activity Monitor, the evidence bundle and the stage labels carry the same facts. See operator-reference.md → Notification mode for the full list. normal restores the one-comment-per-event behaviour.

Tracking and archive issues

Some issues are never meant to be worked or closed: a standing report archive that a workflow appends to every week, a long-lived checklist, a “Keep this issue open” status thread. Mark them with any one of the label hive/tracking, the body marker <!-- hive:tracking -->, or the literal sentence “Keep this issue open” in the body, and the hive treats the issue as a tracking issue.

Issues managed by GitHub Agentic Workflows ([aw] Detection Runs, the weekly research archives, …) are detected automatically, with no hive label needed: any <!-- gh-aw-… --> body marker (gh-aw-detection-runs, gh-aw-expires: …), gh-aw’s boilerplate sentences (“automatically managed by GitHub Agentic Workflows”, “Do not close this issue manually”, “Do not assign to an agent”, case-insensitive), or the agentic-workflows label on an [aw]-prefixed title all count (skip:tracking:gh-aw-<marker|managed|label>). Either way the hive treats the issue as a tracking issue:

  • Not advertised. The good-first-issue picker scores it skip:tracking:<label|marker|keep-open|gh-aw-marker|gh-aw-managed|gh-aw-label> and never adds good first issue / help wanted; a tracking issue that already carries those labels has them withdrawn on the next sweep.
  • Not actionable. Enumeration and the webhook patch sideline it into the filtered bucket with reason tracking (counted as tracking in the repo breakdown), so it never enters the queue, a kick, or the stage engine (it derives to outside the pipeline).
  • Never auto-closed. Every Hive close path goes through the central CloseIssue, which refuses a tracking issue; close-on-merge records tracking_issue as its skip reason, and the already-done, stale, and advisory sweeps inherit the same refusal. Only an owner closing the item from the dashboard overrides it.
  • Closing keywords are nudged. A hive-authored PR whose body says Closes/Fixes #<tracking> has the reference downgraded to Refs with an inline note; a PR created through the hive gets one marked reviewer comment explaining that the issue is an archive and the keyword would be ignored. GitHub itself still honours a Closes #N written by a human on a PR the hive does not own — the owning workflow is expected to recreate its tracking issue in that case.

The hive/tracking label also satisfies the tracker-issue check used by /contribute, so a tracking issue is never handed to an external contributor either.

Not the same thing as the contribute filters. hub.contribute_labels_mode + its label list gate which issues are handed out to external contributors over /contribute — they have never gated the hive’s own agents, so an operator who allow-listed a queue label there (a common setup for routing labeled issues to contributors) still had a hive whose own scanner could work every other open issue. project.issue_filter.require_labels is the agent-side gate; configure both if you want the same label to govern both lanes.

Write-back containment (writeback)

ACMM levels and label policy decide what agents may do. The writeback block decides what the platform may say on GitHub without being asked: sentinel alerts, hold-gate notices, stage labels, supersession and duplicate notices, reporter-trust holds, and so on. Each kind has a minimum level and, on PRs hive did not open, needs the review opt-in label (review.require_labels, fallback hive-review):

writeback:
  unsolicited:
    min_level: 5
    require_labels: true
    backfill: false
  per_repo:
    torch-spyre/torch-spyre: { mode: issues-only }
  kinds:
    sentinel: { min_level: 5, require_label: true, unlabeled_min_level: 6 }

Agent kicks on items already labelled for hive, hive’s own PRs and issues, and /hive command replies are never gated. The default matrix per level is in acmm-policy-matrix.md.

When to add what

Add……when
nothing (name + method + model)you’re starting. Defaults are production defaults.
display_name, emoji, colorthe dashboard roster grows past a handful and you want it scannable
a model pin 📌you need reproducible behavior and the governor keeps optimizing your model away
cli_pinned: truea CLI update broke an agent once and you never want that surprise again
on_demand: truethe agent should run only when something (usually you) explicitly fires it
cadence overridesthe pack’s rhythm doesn’t match your project — a hot repo may want scanner: 15m, a quiet one 4h
pause in a modean agent is noisy exactly when the queue is deep (e.g. pause architect during surge)
stale_timeoutyou changed cadences — keep it above the longest interval
clear_on_kick: falsethe agent genuinely benefits from remembering previous kicks (rare; context bloat is real)
channelsMake the default timer trigger explicit; kick is the only supported type. For event-based work use CEL triggers or work sources, not webhook, schedule, or bead channel types.
tools rulesone agent needs a sharper permission edge than its mode tier provides
a higher ACMM levelyour review capacity, CI trust, and appetite for autonomy have all grown — raise the level and let the pack reconcile the roster
an inference methodyou have GPUs (or a LiteLLM gateway) and want agents off subscription seats

Stage receipt agent report

Agents that hand work from one stage to another can emit a kind: stage_receipt report at AgentReportPath(agentName) under AgentReportDir. The receipt is the validated handoff document; it uses the existing outputschema contract rather than a new store, CRD, or directory.

A stage receipt includes the normal report envelope (lane, kind, findings, prs_opened, beads_filed, and summary) plus a stage_receipt object. Version stage-receipt/v1 requires work_key, assignment_id, generation, stage, contract_revision, execution_key, engine.name, engine.version, input_revision, output_digest, result_class, started_at, ended_at, provenance, and artifacts; remote_run_id and remote_incarnation are optional. started_at and ended_at are RFC3339 timestamps, and ended_at must not be before started_at.

result_class is one of completed, no_change, blocked, failed, or unknown. completed requires at least one artifact. no_change and blocked are separate classes, not successful completion aliases, so a no_change receipt with no artifacts is valid. When artifacts are inline, output_digest must match the stable digest of that artifact set.