---
description: "Authoritative reference for `.hivemind/configs.json` governance rules. Read first when adding, editing, or debugging tool-intelligence policy. Triggers: 'governance rule', 'action.type', 'tool-intelligence config', 'block list', 'allow list', 'config schema'."
agent: hm-platform-references
---

# Config Governance Reference

`.hivemind/configs.json` is the **single source of truth** for runtime governance.
The `ToolIntelligenceEngine` (in `src/features/tool-intelligence/`) reads
`governance.rules[]` at construction time and uses `action.type` to override
the hardcoded default for each rule ID.

## Schema location

- Zod source of truth: `src/schema-kernel/hivemind-configs.schema.ts` (`GovernanceRuleSchema`).
- Generated JSON Schema (IDE-facing): `.hivemind/configs.schema.json` — regenerated by `npm run build`.

## Top-level shape

```jsonc
{
  "document_paths": [".planning/"],   // language-enforcement prefixes
  "governance": {
    "rules": [ /* GovernanceRule[] */ ],
    "naming_standards": { /* optional */ },
    "agent_configs":    { /* optional, per-agent overrides */ },
    "command_agent_mappings": { /* optional, command→agent routing */ },
    "templates":        { /* optional, named content templates */ },
    "tool_registry":    { /* optional, registered custom tools */ }
  }
}
```

## `GovernanceRule` — full schema

```ts
{
  id: string,                                    // required, must match what the engine asks for
  condition: {                                    // required, all fields optional
    toolNames?: string[],                        // e.g. ["task", "delegate-task"]
    sessionIDs?: string[],                       // specific session IDs
    depth?: { min?: number, max?: number }       // delegation depth range (inclusive)
  },
  action: {
    type: "allow" | "warn" | "block" | "escalate" | "needs_jit_grant",  // required
    escalation?: Record<string, unknown>         // optional payload for escalate
  },
  enabled?: boolean                              // default true
}
```

## Action types — semantics

| Type              | Engine behavior                                                      | When to use                                              |
|-------------------|----------------------------------------------------------------------|----------------------------------------------------------|
| `allow`           | Tool call proceeds silently.                                         | Default. Use to permit a tool for a context where you'd otherwise warn. |
| `warn`            | Tool call proceeds; a soft warning is logged + surfaced to the agent.| "I want to know about this, but don't stop it."          |
| `block`           | Tool call is hard-rejected.                                          | Hard safety boundary (e.g. malformed dispatch).          |
| `escalate`        | Treated as `needs_jit_grant` at runtime; requires explicit JIT grant.| Human escalation required.                               |
| `needs_jit_grant` | Tool call is held; an explicit JIT grant must be issued to proceed.  | Recursive task in child session, sensitive tools, etc.   |

**Default severity** when no rule matches: `allow`. Config drives override.

## Built-in rule IDs the engine consults

The `ToolIntelligenceEngine` checks these IDs by name. Add a config rule with
the matching `id` to override the hardcoded fallback.

| Rule ID                       | Hardcoded fallback | What it gates                                       |
|-------------------------------|--------------------|-----------------------------------------------------|
| `R1-malformed-task`           | `block`            | `task` calls missing `subagent_type`.               |
| `R2-child-recursive-task`     | `needs_jit_grant`  | `task` called from a child session without a JIT grant. |
| `R4-delegate-task-code-intent`| `block`            | `delegate-task` whose prompt looks like code editing. |
| `default`                     | `allow`            | Anything that doesn't match a higher-priority rule. |

## Config-driven workflow (step-by-step)

1. **Identify the tool you want to gate.** Find the tool name in
   `TOOL_CAPABILITY_MAP` (`src/features/capability-gate/index.ts`).
2. **Pick an action type** from the table above.
3. **Write the rule** at `.hivemind/configs.json` under `governance.rules[]`:
   ```jsonc
   {
     "id": "my-block-list",
     "condition": { "toolNames": ["my-sensitive-tool"] },
     "action":   { "type": "block" },
     "enabled":  true
   }
   ```
4. **Validate against the schema** (the build step does this automatically):
   ```sh
   node -e "console.log(require('./dist/schema-kernel/hivemind-configs.schema.js').validateConfigsFile(process.cwd()))"
   ```
5. **Reload the engine** (only needed in long-running processes):
   ```ts
   import { resetToolIntelligenceEngine } from "hivemind/features/tool-intelligence"
   resetToolIntelligenceEngine()
   ```
6. **Verify with a test** under `tests/features/tool-intelligence/`.

## Downstream consumers (impact chain)

When you change a rule, the following surfaces pick it up:

| Surface                                  | How it sees the rule                                  |
|------------------------------------------|--------------------------------------------------------|
| `src/features/tool-intelligence/index.ts` | Reads at singleton construction. Lazy, no rebuild needed in dev. |
| `src/hooks/guards/tool-guard-hooks.ts`    | Calls `getToolIntelligenceEngine().evaluateToolCall()` on every `tool.execute.before`. |
| `src/hooks/transforms/contract-enforcement.ts` | Consults `governance.tool_registry` for tool allow-listing. |
| `src/hooks/composition/cqrs-boundary.ts`  | Uses `governance.rules[].condition.depth` to gate write tools. |
| `.opencode/agents/hm-*` (frontmatter `tools:`) | The `tools` field is cross-checked against `governance.rules[].condition.toolNames`. |
| `.opencode/commands/hm-config-govern.md`   | The user-facing command for editing these rules.     |
| `assets/templates/config-rules.template.json` | Drop-in starter. Copy into your config to begin.     |
| `assets/workflows/hm-config-edit.md`        | TUI workflow. Step-by-step edit + validate.          |

## Authoring tips

- **One rule per tool/category.** Avoid mega-rules with 10+ toolNames — split
  for clarity and per-tool `enabled: false` toggles.
- **Use `depth.max: 0`** to apply a rule only to the root session.
- **Use `depth.min: 1`** to apply to all child sessions (the common recursive-task case).
- **Keep `id` stable.** The engine uses the id as a key — renaming is a breaking change.
- **Test after editing.** Add a unit test in `tests/features/tool-intelligence/`
  that asserts the rule's effect on `evaluateToolCall`.

## Anti-patterns

- ❌ Hardcoding severity in code. Always go through `resolveSeverity(id, fallback)`.
- ❌ Adding a new `action.type` without updating both the Zod schema and the runtime `toDecisionKind` map.
- ❌ Setting `action.type: "block"` on a rule that should be overridable. Use `warn` if you want soft.
- ❌ Leaving `enabled: false` rules in production config. Remove or set `enabled: true`.

## Validation command

```sh
node -e "const r=require('./dist/schema-kernel/hivemind-configs.schema.js').validateConfigsFile(process.cwd()); console.log(r.success ? 'VALID' : 'INVALID: '+r.error)"
```