# Claude Runtime Reference

Claude-runtime behavior only. Global rules win if anything here conflicts.

## Required Actions

1. Follow the Session Start load order in `~/.config/mosaic/AGENTS.md`.
2. Runtime config lives in `~/.claude/settings.json` (hooks, model, plugins, permissions) and
   `~/.claude/hooks-config.json`.
3. sequential-thinking MCP is required.
4. First response MUST declare mode per the global contract.
5. Git wrappers first for issue/PR/milestone ops; runtime-default confirmation prompts do NOT
   override Mosaic hard gates (push/merge/issue-close without routine confirmation).

## Subagent Model Selection (Claude Code syntax)

The Task tool takes `model`: `"haiku"` | `"sonnet"` | `"opus"`. You MUST set it per the tier rule
in AGENTS.md — omitting it defaults to the parent (usually opus) and wastes budget.

```
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review src/auth/ changes")
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")
```

## Memory Policy (Hard Gate)

OpenBrain is the primary cross-agent memory layer — capture learnings/gotchas/decisions there
(`capture` MCP tool or REST). `~/.claude/projects/*/memory/MEMORY.md` is **write-blocked** by the
`prevent-memory-write.sh` PreToolUse hook (the rule alone proved insufficient — the hook is the
hard gate). At session start, `search(topic)` + `recent()` to load prior context. Full protocol:
`~/.config/mosaic/guides/MEMORY.md`.

Quick placement: discoveries/decisions → OpenBrain; active task state → `docs/TASKS.md` or
`docs/scratchpads/`; Mosaic framework notes → `~/.config/mosaic/memory/`.

## MCP Configuration

MCP servers are configured in `~/.claude.json` (key `mcpServers`) — NOT `~/.claude/settings.json`,
where that key is ignored. `settings.json` controls hooks/model/plugins/permissions.

```bash
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
claude mcp add --scope user <name> -- npx -y <package>   # stdio
```

`--scope user` → `~/.claude.json` (global); `project` → `.claude/settings.json`; `local` (default)
→ not committed.

## Required Settings (launcher-audited, advisory)

`mosaic claude` warns if `~/.claude/settings.json` is missing these (session still launches):

- **Hooks** — PreToolUse `prevent-memory-write.sh` (Write|Edit|MultiEdit); PostToolUse
  `qa-hook-stdin.sh` + `typecheck-hook.sh` (Edit|MultiEdit|Write).
- **Plugins** — `feature-dev`, `pr-review-toolkit`, `code-review`.
- **Settings** — `enableAllMcpTools: true`; `model: "opus"` (orchestrator default; workers use
  tiered models via the Task `model` param).

Note: PostToolUse hook plain stdout on exit 0 goes to the debug log, not model context — only
`hookSpecificOutput.additionalContext` (or exit-2 stderr) enters context.