# Claude Runtime Reference

## Runtime Scope

This file applies only to Claude runtime behavior.

## Required Actions

1. Follow global load order in `~/.config/mosaic/AGENTS.md`.
2. Use `~/.claude/settings.json` and `~/.claude/hooks-config.json` as runtime config sources.
3. Treat sequential-thinking MCP as required.
4. If runtime config conflicts with global rules, global rules win.
5. Documentation rules are inherited from `~/.config/mosaic/AGENTS.md` and `~/.config/mosaic/guides/DOCUMENTATION.md`.
6. For issue/PR/milestone actions, run Mosaic git wrappers first (`~/.config/mosaic/tools/git/*.sh`) and do not call raw `gh`/`tea`/`glab` first.
7. For orchestration-oriented missions, load `~/.config/mosaic/guides/ORCHESTRATOR.md` before acting.
8. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...`
9. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.

## Subagent Model Selection (Claude Code Syntax)

Claude Code's Task tool accepts a `model` parameter: `"haiku"`, `"sonnet"`, or `"opus"`.

You MUST set this parameter according to the model selection table in `~/.config/mosaic/AGENTS.md`. Do NOT omit the `model` parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well.

**Examples:**

```
# Codebase exploration — haiku
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")

# Code review — sonnet
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/")

# Standard feature work — sonnet
Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form")

# Complex architecture — opus (only when justified)
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")
```

**Quick reference (from global AGENTS.md):**

| haiku                  | sonnet            | opus                       |
| ---------------------- | ----------------- | -------------------------- |
| Search, grep, glob     | Code review       | Complex architecture       |
| Status/health checks   | Test writing      | Security/auth logic        |
| Simple one-liner fixes | Standard features | Ambiguous design decisions |

## Memory Policy (Hard Gate)

**OpenBrain is the primary cross-agent memory layer.** All agent learnings, gotchas, decisions, and project state MUST be captured to OpenBrain via the `capture` MCP tool or REST API.

`~/.claude/projects/*/memory/MEMORY.md` files are **write-blocked by PreToolUse hook** (`prevent-memory-write.sh`). Any attempt to write agent learnings there will be rejected with an error directing you to OpenBrain.

### What belongs where

| Content                                         | Location                                                               |
| ----------------------------------------------- | ---------------------------------------------------------------------- |
| Discoveries, gotchas, decisions, observations   | OpenBrain `capture` — searchable by all agents                         |
| Active task state                               | `docs/TASKS.md` or `docs/scratchpads/`                                 |
| Behavioral guardrails that MUST be in load-path | `MEMORY.md` (read-mostly; write only for genuine behavioral overrides) |
| Mosaic framework technical notes                | `~/.config/mosaic/memory/`                                             |

### Using OpenBrain

At session start, load prior context:

```
search("topic or project name")   # semantic search
recent(limit=5)                    # what's been happening
```

When you discover something:

```
capture("The thing you learned", source="project/context", metadata={"type": "gotcha", ...})
```

### Why the hook exists

Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.

## MCP Configuration

**MCPs are configured in `~/.claude.json` — NOT `~/.claude/settings.json`.**

`settings.json` controls hooks, model, plugins, and allowed commands.
`~/.claude.json` is the global Claude Code state file where `mcpServers` lives.

To register an MCP server that persists across all sessions:

```bash
# HTTP MCP (e.g. OpenBrain)
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"

# stdio MCP
claude mcp add --scope user <name> -- npx -y <package>
```

`--scope user` = writes to `~/.claude.json` (global, all projects).
`--scope project` = writes to `.claude/settings.json` in project root.
`--scope local` = default, local-only (not committed).

Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.

## Required Claude Code Settings (Enforced by Launcher)

The `mosaic claude` launcher validates that `~/.claude/settings.json` contains the required Mosaic configuration. Missing or outdated settings trigger a warning at launch.

**Required hooks:**

| Event       | Matcher                  | Script                    | Purpose                                        |
| ----------- | ------------------------ | ------------------------- | ---------------------------------------------- |
| PreToolUse  | `Write\|Edit\|MultiEdit` | `prevent-memory-write.sh` | Block writes to `~/.claude/projects/*/memory/` |
| PostToolUse | `Edit\|MultiEdit\|Write` | `qa-hook-stdin.sh`        | QA report generation after code edits          |
| PostToolUse | `Edit\|MultiEdit\|Write` | `typecheck-hook.sh`       | Inline TypeScript type checking                |

**Required plugins:**

| Plugin              | Purpose                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `feature-dev`       | Subagent architecture: code-reviewer, code-architect, code-explorer                                      |
| `pr-review-toolkit` | PR review: code-simplifier, comment-analyzer, test-analyzer, silent-failure-hunter, type-design-analyzer |
| `code-review`       | Standalone code review capabilities                                                                      |

**Required settings:**

- `enableAllMcpTools: true` — Allow all configured MCP tools without per-tool approval
- `model: "opus"` — Default to opus for orchestrator-level sessions (workers use tiered models via Task tool)

If `mosaic claude` detects missing hooks or plugins, it will print a warning with the exact settings to add. The session will still launch — enforcement is advisory, not blocking — but agents operating without these settings are running degraded.