/gaia-patterns

name: gaia-patterns
description: Use when building or modifying Gaia components -- agents, skills, hooks, CLI tools, or routing config

Gaia Code Patterns

Construction patterns for building Gaia components. Every component type follows a discoverable pattern -- read 2-3 existing examples before creating a new one. For the full component inventory, see `reference.md`.

Prompt -> Result Flow

1. User sends prompt
   |
2. Orchestrator routes to agent (DB-backed surface_routing table --
   the routing is the ORCHESTRATOR's reasoning; it is never injected
   into the subagent)
   |
3. Pre-Tool Hook (pre_tool_use.py)
   +-- Validate the Task/Agent dispatch (agent exists, T3 scan of the
       prompt via TaskValidator) -- no frontmatter read, no skill load
   +-- Birth the agent_contract_handoffs row (identity, kernel data,
       dispatch_project resolved from cwd)
   |
   (for a dispatched SUBAGENT only: the HOST -- Claude Code, not this
   hook or any other Gaia hook -- separately reads the target agent's
   `.md` frontmatter and preloads its `skills:` list before the first
   turn. `hooks/hooks.json` has no PreToolUse `Skill` matcher; its
   PostToolUse `Skill` matcher only records loads: every load becomes a
   `skill.loaded` harness event naming the skill, agent, role and
   session (`hooks/modules/events/capability_usage.py`), and a
   main-session `Skill('memory')` load also becomes `memory.skill_loaded`
   for the orchestrator's memory-write guard
   (`hooks/modules/security/memory_skill_guard.py`) -- see
   `artifact_skill_reminder.py`. A preloaded skill never passes through
   the `Skill` tool, so it records nothing. The primary agent has no equivalent:
   Claude Code's own docs list only "system prompt, tool restrictions,
   and model" as inherited on the main thread, which is why
   `gaia-orchestrator.md`'s frontmatter carries no `skills:` field.)
   |
4. SubagentStart hook claims the born row and injects the KERNEL:
   "# Your Contract" (incl. project, its declared workflow when
   there is one, can_read/can_write menu), "# Scope memory",
   "# Project context", "# Standing notes", "# Environment", "# Your CLI".
   "# Project context" carries the dispatch project's can_read sections: whole
   when they fit, else pointer lines, else one line; the verbs for the rest
   are in agent-protocol/read-map.md.
   |
5. Agent checkpoints/finalizes its agent_contract_handoffs row via
   `gaia contract`; the final message carries no envelope
   |
6. Post-Tool Hook -> audit + metrics
   |
7. Orchestrator processes agent_state; only COMPLETE is terminal

Hook Patterns

Entry points (`hooks/*.py`) are stdin/stdout glue only. All logic lives in the adapter layer.

hooks/pre_tool_use.py          -- reads stdin, calls adapter, writes stdout
  -> adapters/claude_code.py   -- parses event, formats the host response
                                  (adapters/opencode.py is OpenCode's)
    -> adapters/tool_policy.py -- the shared tool policy both adapters call
    -> gaia/approvals/core.py  -- the host-neutral approval core
    -> modules/security/*      -- blocked_commands, mutative_verbs
    -> modules/context/*       -- contracts_loader, kernel_builder
    -> modules/agents/*        -- dispatch_binding, artifact_skill_map

**To add a new module:** Write module in `modules/<package>/`, import and call it from the relevant adapter method. Modules receive parsed context and return results; they never read stdin or write stdout.

**To add a new hook entry point:** Create `hooks/<event_name>.py`, register it in `build/<plugin>.manifest.json`, add matchers. The entry point reads stdin JSON, calls the adapter, and prints the response.

Agent Patterns

---
name: agent-name
description: Routing label -- triggers when orchestrator sees matching intent
tools: Read, Edit, Write, Glob, Grep, Bash  # restrict per domain
model: inherit
permissionMode: acceptEdits  # required for most agents; omit only for orchestrator and read-only agents
skills:
  - agent-protocol        # always first
  - security-tiers        # always second
  - command-execution     # if agent runs commands
  - domain-skill          # agent's domain patterns
cli:
  - "gaia <domain-verb> ..."   # optional; appends a line to "# Your CLI"
---

**Identity** (1-2 paragraphs): domain, output format. **Scope**: CAN DO / CANNOT DO -> DELEGATE table. **Domain Errors**: agent-specific errors only.

`skills:` and `cli:` are read by two different parties, not one -- this is why the example shows both. `skills:` is preloaded by the HOST (Claude Code), not by any Gaia hook, and only for a dispatched SUBAGENT: the primary agent (`gaia-orchestrator.md`) carries no `skills:` field, because Claude Code's own docs list only "system prompt, tool restrictions, and model" as inherited on the main thread. `cli:` is the one frontmatter field Gaia itself reads, at subagent birth (`context/kernel_builder.py::_agent_cli_extras`): its lines are appended verbatim to the "# Your CLI" kernel block. It is optional and no shipped agent declares it yet -- shown here so the two fields' different owners (host vs. Gaia) are visible side by side, not to imply it is required.

A dispatched SUBAGENT is instantiated as: identity (.md) + skills (preloaded by the host from frontmatter) + dispatch kernel (# Your Contract / # Scope memory / # Project context / # Standing notes / # Environment / # Your CLI, rendered from the born row) + orchestrator request. The primary agent skips the skills step entirely. Project context arrives as the kernel's `# Project context` block, built from the `can_read` sections (from `agent_contract_permissions`) of `project_context_contracts`; a section the block only points at is pulled on demand -- the verb that reaches it, and the same-named sibling that does not, are in `agent-protocol/read-map.md`.

Routing Patterns

The DB-backed `surface_routing` table maps user intent to agents. The source of truth i