Claude Runtime Reference

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

Required Actions

Follow the Session Start load order in ~/.config/mosaic/AGENTS.md.
Runtime config lives in ~/.claude/settings.json (hooks, model, plugins, permissions) and ~/.claude/hooks-config.json.
sequential-thinking MCP is required.
First response MUST declare mode per the global contract.
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.

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.

2.9 KiB Raw Blame History