coding-os 0.3.2__py3-none-any.whl

adapters/claude/README.md

@@ -0,0 +1,6 @@
+# Claude adapter (mRNA layer)
+
+- **Install:** `bash src/adapters/claude/install.sh` (or `make sync`).
+- **Manifest:** [adapter.yaml](adapter.yaml) — hook capabilities, MCP launch metadata, optional `presence` block for Hub board pills.
+- **Agent SDK:** [sdk_dispatcher.py](sdk_dispatcher.py) and other adapter-local scripts. Per **P8** in repo `AGENTS.md`, do not import adapter SDK code from `src/core/**`.
+- **Architecture checklist:** Anthropic Certified Architect foundations guide (repo copy under `docs/code-os-core-docs/instructor_Claude+Certified+Architect+–+Foundations+Certification+Exam+Guide.md`) — hooks / MCP / session topics map to this adapter + `src/core/hooks/`; see [docs/engineering/adapter-parity.md](../../docs/engineering/adapter-parity.md).

adapters/claude/_install_helpers/extract_stacks.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""
+Extract installed stack names from .coding-os/installed-manifest.json.
+
+Called from install.sh (form B — separate file, NOT a heredoc) because
+Homebrew bash 5.3.9 sporadically deadlocks BOTH `python3 - <<HEREDOC`
+AND nested `$(python3 -c "$(cat <<'PY' ... PY)")` patterns inside
+$(...) command substitutions. A standalone `.py` invoked as
+`python3 path/to/file.py args` has no heredoc → no bug surface.
+
+USAGE:
+    python3 extract_stacks.py <manifest_path>
+
+OUTPUT:
+    space-separated stack names on stdout, e.g. "django nextjs"
+    Empty stdout + exit 0 when manifest has no templates.
+    Exit 1 + stderr message on parse error.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        sys.stderr.write(f"usage: {argv[0]} <manifest_path>\n")
+        return 2
+    try:
+        with open(argv[1]) as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        return 0  # no manifest yet — silent, install.sh skips the LINKER
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"manifest parse error: {exc}\n")
+        return 1
+    print(" ".join(data.get("templates", [])))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

adapters/claude/_install_helpers/update_mcp_json.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""
+Add/refresh the `coding-os` entry in a project's .mcp.json.
+
+Called from install.sh (form B — separate file, NOT a heredoc) because
+Homebrew bash 5.3.9 sporadically deadlocks BOTH `python3 - <<HEREDOC`
+AND nested `$(python3 -c "$(cat <<'PY' ... PY)" ...)` inside $(...).
+A standalone `.py` invoked as `python3 path/to/file.py args` has no
+heredoc surface → no bug.
+
+USAGE:
+    python3 update_mcp_json.py <mcp_file> <coding_os_root>
+
+WHEN `cos` IS ON PATH:
+    {"command": "cos", "args": ["server-start"]}
+WHEN NOT (fresh install before `uv tool install`):
+    fallback to absolute `uv run` form anchored at `coding_os_root`.
+
+EXIT
+    0 on success (or no-op when JSON would be unchanged).
+    1 on bad existing JSON (caller logs WARN; install proceeds).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 3:
+        sys.stderr.write(f"usage: {argv[0]} <mcp_file> <coding_os_root>\n")
+        return 2
+
+    mcp_path = Path(argv[1])
+    cos_root = argv[2]
+    has_cos = shutil.which("cos") is not None
+
+    try:
+        with mcp_path.open() as f:
+            data = json.load(f)
+    except FileNotFoundError:
+        data = {}
+    except json.JSONDecodeError as exc:
+        sys.stderr.write(f"  ERROR: {mcp_path} is not valid JSON: {exc}\n")
+        return 1
+
+    data.setdefault("mcpServers", {})
+    if has_cos:
+        data["mcpServers"]["coding-os"] = {
+            "command": "cos",
+            "args": ["server-start"],
+        }
+    else:
+        data["mcpServers"]["coding-os"] = {
+            "command": "uv",
+            "args": [
+                "run",
+                "--directory",
+                f"{cos_root}/core/thinking_os",
+                "python",
+                "server.py",
+            ],
+            "cwd": "${workspaceFolder}",
+        }
+
+    with mcp_path.open("w") as f:
+        json.dump(data, f, indent=2)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

adapters/claude/adapter.yaml

@@ -0,0 +1,164 @@
+version: 1
+id: claude
+label: "Anthropic Claude Code"
+
+# Hub chat model picker — adapter→models SSOT (served by /api/config/adapters).
+# runtime: in_process ⇒ runnable via the Claude Agent SDK inside Hub chat.
+runtime: in_process
+models:
+  - id: claude-fable-5
+    label: "Fable 5"
+  - id: claude-opus-4-8
+    label: "Opus 4.8"
+    default: true
+  - id: claude-sonnet-5
+    label: "Sonnet 5"
+  - id: claude-haiku-4-5
+    label: "Haiku 4.5"
+# Reasoning-effort levels the Claude Agent SDK accepts (EffortLevel) — shown in
+# the Hub chat composer so a turn can be weighted per adapter.
+efforts: [low, medium, high, xhigh, max]
+default_effort: high
+
+# Hub chat live-status vocabulary. tool_labels turns a runtime tool name into a
+# friendly present-participle (real status: Read -> "Reading"); idle_phrases are
+# playful words rotated while the agent works without a concrete tool (our side).
+# Data-driven so a new adapter (Codex) ships its own with zero frontend change.
+chat_status:
+  tool_labels:
+    Read: Reading
+    Grep: Searching
+    Glob: Searching
+    Bash: Running
+    Edit: Editing
+    Write: Writing
+    MultiEdit: Editing
+    NotebookEdit: Editing
+    Task: Delegating
+    Agent: Delegating
+    WebFetch: Fetching
+    WebSearch: Searching the web
+    TodoWrite: Planning
+  idle_phrases: [working, thinking, cooking, crunching, noodling, percolating, pondering, churning]
+
+# Hub board pills + presence contract (see docs/engineering/adapter-parity.md).
+presence:
+  signal: hook_timestamps
+  hub_glyph: "Cl"
+  hub_color: "#d97706"
+  # Events Claude Code's hook spec actually fires; SessionEnd is not in the
+  # spec — Stop is the canonical session-end signal — so it is omitted.
+  # 2026-05-04: SDK 0.1.73 also fires SubagentStart/Stop and
+  # PostToolUseFailure — declared so the agent-presence hook stays
+  # accurate while sub-agents work and when tools error out.
+  presence_events:
+    - SessionStart
+    - UserPromptSubmit
+    - PreToolUse
+    - PostToolUse
+    - PostToolUseFailure
+    - SubagentStart
+    - SubagentStop
+    - Stop
+settings_file: ".claude/settings.json"
+hooks_dir: ".claude/hooks"
+rules_dir: ".claude/rules"
+skills_dir: ".claude/skills"
+commands_dir: ".claude/commands"
+sourced_hooks: [cos-env.sh]
+supports_rules: true
+supports_settings_json: true
+install_script: install.sh
+
+# CLI binary discovery (consumed by cli/doctor.py — keeps that file free of
+# hardcoded "claude" literals; Rule 11). cli_binary is the executable name to
+# look up via shutil.which; sdk_package is the importable Python package whose
+# version doctor reports.
+cli_binary: claude
+sdk_package: claude-agent-sdk
+auth_env_vars: [ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN]
+
+# Env vars the Claude Code runtime exports to hook subprocesses / the CLI
+# shell.  Consumed by cli/board_commands.py::_detect_agent_runtime so the
+# CLI can attribute agent_session correctly without hardcoded literals
+# (see rule #11). CLAUDE_PROJECT_DIR is intentionally omitted — other
+# IDE runtimes also set it as a workspace alias, so it's not a reliable
+# Claude signal.
+runtime_env_markers:
+  - CLAUDECODE
+  - CLAUDE_CODE_SSE_PORT
+  - CLAUDE_CODE_ENTRYPOINT
+  - CLAUDE_AGENT_SDK_VERSION
+
+# Per-panel session identity — declares how cos_panel_upgrade_from_payload
+# (src/core/hooks/cos-env.sh) derives the panel id from this agent's hook
+# stdin payload, and which env vars the agent runtime exports as fallback.
+# Adding a new adapter (e.g. gemini) = add this block to its adapter.yaml;
+# no code change in src/core/hooks/ or src/cli/ (Rule 11 data-driven).
+#
+# stdin_field: JSON key in the hook stdin payload carrying the panel id.
+#   Claude Code spec: every hook event payload has `session_id` (UUID).
+# env_vars: priority-ordered fallback when stdin is unavailable
+#   (e.g. raw bash test, hook helpers that don't slurp stdin).
+runtime_session_marker:
+  stdin_field: session_id
+  env_vars:
+    # CLAUDE_CODE_SESSION_ID is what Claude Code actually exports to hook
+    # subprocesses (verified 2026-06-01). It must lead — the earlier
+    # CLAUDE_SESSION_ID guess never matched, so panel-id fell through to the
+    # unstable ppid fallback. Kept after it as a forward-compat alias.
+    - CLAUDE_CODE_SESSION_ID
+    - CLAUDE_SESSION_ID
+    # ANTHROPIC_SESSION_ID intentionally absent: cos-env.sh's probe dropped it
+    # and the shell kernel never reads it, so declaring it here is a
+    # silently-dead marker. test_adapter_session_marker_probe_parity enforces
+    # env_vars ⊆ the cos-env.sh probe so this cannot drift back.
+
+# MCP launch metadata consumed by cli/doctor.py::_load_coding_os_mcp_launch
+# (C15 check). Data-driven so tests/test_no_hardcoded_stacks.py stays green.
+mcp_launch:
+  loader: claude_json      # maps to cli.doctor._load_claude_json
+  config_paths:
+    - scope: project
+      path: .mcp.json
+
+# Deep-merged with aggregated hooks by render_settings_json().
+# Phase 1: empty — adapter's existing install.sh already writes settings.json.
+default_settings: {}
+
+# Output file the renderer writes to (relative to adapters/claude/).
+hook_registry_output: settings.template.json
+
+# Hook capabilities — which {event, matcher} pairs this agent can trigger.
+# Used by cli/hook_renderer.py to filter core/hooks/registry.yaml entries
+# when rendering settings.template.json. A hook whose event/matcher is
+# not in this list is skipped for this adapter.
+#
+# Source: per-event matchers observed in the live Claude Code hook spec.
+hook_capabilities:
+  PreToolUse:
+    matchers: [Bash, "Write|Edit", "Write|Edit|MultiEdit", Skill, Read, "mcp__coding-os__cos_task_move", "mcp__coding-os__cos_task_create", "mcp__coding-os__cos_work_log_append"]
+    # cos_task_move added (TASK-409): sync-task-current fires PostToolUse on
+    # this matcher to auto-write .task-current after an MCP task move; without
+    # it the pair rendered for zero adapters and the marker went stale.
+  PostToolUse:
+    matchers: [Bash, "Write|Edit", "Write|Edit|MultiEdit", Skill, "mcp__coding-os__cos_backtrack_log", "mcp__coding-os__cos_task_move"]
+  # PostToolUseFailure (SDK 0.1.73): fires when a tool errored. Empty
+  # matcher = match all tools; presence/observation hooks keep the
+  # board's activity signal accurate even on failures.
+  PostToolUseFailure:
+    matchers: [""]
+  Stop:
+    matchers: [""]
+  # Subagent lifecycle (SDK 0.1.73 native; previously TS-only).
+  SubagentStart:
+    matchers: [""]
+  SubagentStop:
+    matchers: [""]
+  SessionStart:
+    matchers: [startup, "compact|resume"]
+  # UserPromptSubmit powers the agent-presence hook's "user turn in
+  # flight" signal so the live-agents panel knows the session is
+  # actively working even between tool calls.
+  UserPromptSubmit:
+    matchers: [""]

adapters/claude/hooks/README.md

@@ -0,0 +1,40 @@
+<!-- domain:ADAPTERS | layer:reference | ssot:false | updated:2026-05-05 -->
+# Claude-private hooks
+
+Scripts here are **only installed into `.claude/hooks/`** of consumer
+projects whose adapter is `claude`. They are NOT visible to Codex,
+Gemini, or any future adapter.
+
+Use this directory when a hook depends on an event/matcher that ONLY
+the Claude SDK fires (`SubagentStart`, `PostToolUseFailure`,
+`PermissionRequest`, …) or on Claude-specific environment variables
+(`CLAUDE_PROJECT_DIR`, `CLAUDE_AGENT_SDK_VERSION`, …).
+
+If a hook is genuinely cross-adapter, keep it under `src/core/hooks/` and
+declare its capabilities through `src/adapters/<agent>/adapter.yaml`.
+
+## Render order (D4)
+
+`src/cli/hook_renderer.py` walks both directories. Adapter-private files
+take precedence on name clash, so a `src/core/hooks/foo.sh` can be replaced
+by `src/adapters/claude/hooks/foo.sh` without touching the registry.
+
+`src/core/scripts/install-adapter.sh` symlinks core hooks first, then the
+adapter-private layer second — `ln -sf` rebinds the symlink atomically,
+so the adapter-private file wins by the end of install.
+
+## Conventions
+
+- Each script must source `cos-env.sh` for shared env (`COS_AGENT_DIR`,
+  `COS_DB_PATH`, …).
+- Each script must `exit 0` on unexpected input (fail-open) unless it is
+  a deny / block hook (`exit 2`, with a clear stderr message).
+- Register the hook in `src/core/hooks/registry.yaml` using
+  `adapter_scope: claude` so the renderer emits it only for Claude.
+- Keep cross-adapter scripts under `src/core/hooks/`. Move into this
+  directory ONLY if the script can never serve another adapter.
+
+## Existing scripts
+
+(currently empty — see checklist `T4.4`–`T4.5` for
+pending Claude-only scripts that move here from src/core/hooks.)

adapters/claude/hooks/agent_memory_sync.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Render Trusted lessons into .agents/memory/MEMORY.md and harvest foreign notes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+
+_PHYSICAL = Path(__file__).resolve()
+_THINKING_OS = _PHYSICAL.parents[3] / "core" / "thinking_os"
+if _THINKING_OS.is_dir() and str(_THINKING_OS) not in sys.path:
+    sys.path.insert(0, str(_THINKING_OS))
+
+GENERATED_START = "<!-- cos:generated:start — do not edit or re-import; source: coding-os DB -->"
+GENERATED_END = "<!-- cos:generated:end -->"
+GENERATED_BLOCK_RE = re.compile(
+    r"<!-- cos:generated:start.*?-->.*?<!-- cos:generated:end -->", re.DOTALL
+)
+MAX_GENERATED_LINES = 200
+LEDGER_NAME = ".harvested.json"
+
+
+def _trusted_lessons(conn) -> list[dict]:
+    rows = conn.execute(
+        "SELECT pattern, times_seen FROM learned_patterns "
+        "WHERE confidence >= 0.7 AND times_seen >= 3 "
+        "AND COALESCE(memory_type, '') != 'stat' AND promoted_to IS NULL "
+        "ORDER BY confidence * COALESCE(impact_score, 0.5) DESC "
+        "LIMIT 60"
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def render_mirror(memory_dir: Path, lessons: list[dict]) -> None:
+    from sanitizer import redact_secrets
+
+    lines = [GENERATED_START, "## Trusted lessons (auto-generated)", ""]
+    for lesson in lessons:
+        text, _ = redact_secrets((lesson["pattern"] or "").strip())
+        lines.append(f"- {text} _(seen {lesson['times_seen']}×)_")
+        if len(lines) >= MAX_GENERATED_LINES - 1:
+            break
+    lines.append(GENERATED_END)
+    block = "\n".join(lines)
+
+    memory_md = memory_dir / "MEMORY.md"
+    existing = memory_md.read_text(encoding="utf-8", errors="replace") if memory_md.exists() else ""
+    if GENERATED_BLOCK_RE.search(existing):
+        updated = GENERATED_BLOCK_RE.sub(lambda _: block, existing, count=1)
+    elif existing.strip():
+        updated = f"{block}\n\n{existing}"
+    else:
+        updated = block + "\n"
+    memory_md.write_text(updated, encoding="utf-8")
+
+
+def _foreign_sections(memory_dir: Path) -> list[str]:
+    sections: list[str] = []
+    for md_file in sorted(memory_dir.glob("*.md")):
+        text = md_file.read_text(encoding="utf-8", errors="replace")
+        text = GENERATED_BLOCK_RE.sub("", text)
+        for chunk in re.split(r"\n(?=## )", text):
+            chunk = chunk.strip()
+            # A harvestable note needs a heading AND a body — bare index
+            # headers, frontmatter and link lists carry no lesson.
+            if len(chunk) < 100 or "\n" not in chunk or chunk.startswith("---"):
+                continue
+            sections.append(chunk[:2000])
+    return sections
+
+
+def harvest(memory_dir: Path, conn) -> int:
+    from tools.learning import _upsert_pattern
+
+    ledger_path = memory_dir / LEDGER_NAME
+    try:
+        seen = set(json.loads(ledger_path.read_text(encoding="utf-8")))
+    except Exception:
+        seen = set()
+
+    minted = 0
+    for section in _foreign_sections(memory_dir):
+        digest = hashlib.sha256(section.encode()).hexdigest()[:16]
+        if digest in seen:
+            continue
+        seen.add(digest)
+        result = _upsert_pattern(
+            conn,
+            pattern=section.split("\n", 1)[0].lstrip("# ").strip()[:300],
+            memory_type="pattern",
+            domain=None,
+            source="import",
+            confidence=0.5,
+            concepts=json.dumps(["import", "agents-memory"]),
+        )
+        if result.get("id"):
+            minted += 1
+    conn.commit()
+    ledger_path.write_text(json.dumps(sorted(seen), indent=0), encoding="utf-8")
+    return minted
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 3:
+        return 0
+    db_path, memory_dir_raw = argv[1], argv[2]
+    memory_dir = Path(memory_dir_raw)
+    if not Path(db_path).exists():
+        return 0
+    memory_dir.mkdir(parents=True, exist_ok=True)
+
+    from database import get_connection
+
+    conn = get_connection(db_path)
+    try:
+        minted = harvest(memory_dir, conn)
+        render_mirror(memory_dir, _trusted_lessons(conn))
+        print(f"agent-memory sync: mirror rendered, {minted} foreign note(s) harvested")
+    finally:
+        conn.close()
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except Exception:
+        sys.exit(0)

adapters/claude/hooks/ensure-agent-memory-link.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Ensure the harness memory dir is a symlink into the repo's committed
+# .agents/memory (portable agent memory — survives clone/laptop swap).
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+command -v cos_log_hook >/dev/null 2>&1 || cos_log_hook() { :; }
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$PWD}")"
+REPO_MEM="$REPO_ROOT/.agents/memory"
+SLUG="$(printf '%s' "$REPO_ROOT" | sed 's#/#-#g')"
+HARNESS_MEM="$HOME/.claude/projects/$SLUG/memory"
+
+cos_log_hook ensure-agent-memory-link fire "slug=$SLUG" || true
+
+mkdir -p "$REPO_MEM"
+
+if [ -L "$HARNESS_MEM" ]; then
+  if [ "$(readlink "$HARNESS_MEM")" = "$REPO_MEM" ]; then
+    exit 0
+  fi
+  rm "$HARNESS_MEM"
+elif [ -d "$HARNESS_MEM" ]; then
+  # Migrate without clobber: an existing repo file wins over the machine copy.
+  for file in "$HARNESS_MEM"/* "$HARNESS_MEM"/.[!.]*; do
+    [ -e "$file" ] || continue
+    name="$(basename "$file")"
+    [ -e "$REPO_MEM/$name" ] || mv "$file" "$REPO_MEM/$name"
+  done
+  rmdir "$HARNESS_MEM" 2>/dev/null || mv "$HARNESS_MEM" "$HARNESS_MEM.bak-$(date +%Y%m%d%H%M%S)"
+fi
+
+mkdir -p "$(dirname "$HARNESS_MEM")"
+ln -s "$REPO_MEM" "$HARNESS_MEM"
+cos_log_hook ensure-agent-memory-link allow "linked=$HARNESS_MEM" || true
+exit 0

adapters/claude/hooks/sync-agent-memory.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Stop hook: mirror Trusted lessons into .agents/memory/MEMORY.md and harvest
+# foreign notes back into the DB (hash-deduped). Fail-open observability.
+set -euo pipefail
+
+source "$(dirname "$0")/cos-env.sh" 2>/dev/null || true
+command -v cos_log_hook >/dev/null 2>&1 || cos_log_hook() { :; }
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-$PWD}")"
+REPO_MEM="$REPO_ROOT/.agents/memory"
+DB_PATH="${COS_DB_PATH:-$REPO_ROOT/.coding-os/coding-os.db}"
+
+[ -d "$REPO_MEM" ] || exit 0
+[ -f "$DB_PATH" ] || exit 0
+
+HELPER="$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")/agent_memory_sync.py"
+[ -f "$HELPER" ] || exit 0
+
+cos_log_hook sync-agent-memory fire "dir=$REPO_MEM" || true
+python3 "$HELPER" "$DB_PATH" "$REPO_MEM" 2>/dev/null || true
+exit 0

adapters/claude/install.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Claude adapter installer for coding-os.
+#
+# Thin wrapper: delegates the common install work (dirs, hooks, rules,
+# skills, commands, role prompts, agent identity) to
+# src/core/scripts/install-adapter.sh, then performs Claude-specific
+# finalization (settings.json render, .mcp.json).
+#
+# History: prior versions also symlinked role files into .claude/agents/
+# anticipating an AgentDefinition-driven dispatch path. Decision D2 of
+# (2026-05-05) keeps `query()`-per-formula because role
+# sub-sessions need their own permission_mode + MCP + hooks; the
+# AgentDefinition path would force inheritance from the parent.
+# .claude/agents/ symlinks were therefore removed — slash-command
+# role prompts still ship via .claude/commands/role-*.md.
+set -euo pipefail
+shopt -s nullglob
+
+CODING_OS_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+PROJECT_ROOT="${PWD}"
+
+echo "⚙️  Installing coding-os Claude adapter..."
+echo "  Project: $PROJECT_ROOT"
+echo "  coding-os: $CODING_OS_ROOT"
+
+# 1-8. Common install steps (shared with codex).
+bash "${CODING_OS_ROOT}/core/scripts/install-adapter.sh" \
+  --adapter claude --agent-dir .claude \
+  --coding-os-root "$CODING_OS_ROOT" --project-root "$PROJECT_ROOT"
+
+# 9. settings.json from registry-rendered template.
+TEMPLATE="${CODING_OS_ROOT}/adapters/claude/settings.template.json"
+HOOKS_REL=".claude/hooks"
+sed "s|{{HOOKS_DIR}}|${HOOKS_REL}|g" "$TEMPLATE" > "${PROJECT_ROOT}/.claude/settings.json"
+
+# 10. .mcp.json — register thinking_os MCP server entry.
+MCP_FILE="${PROJECT_ROOT}/.mcp.json"
+if [[ ! -f "$MCP_FILE" ]]; then
+  cat > "$MCP_FILE" << 'MCPEOF'
+{
+  "mcpServers": {}
+}
+MCPEOF
+fi
+MCP_HELPER="${CODING_OS_ROOT}/adapters/claude/_install_helpers/update_mcp_json.py"
+if [[ -f "$MCP_HELPER" ]]; then
+  python3 "$MCP_HELPER" "$MCP_FILE" "$CODING_OS_ROOT" \
+    || echo "  WARN: Could not update .mcp.json automatically (see error above)"
+else
+  echo "  WARN: helper missing at $MCP_HELPER — .mcp.json not updated"
+fi
+
+# 11. Strip any pre-Q.deep .claude/agents/ symlinks — D2 retired the
+# AgentDefinition path; presence of these symlinks was misleading
+# because the dispatcher uses query() not the Agent tool.
+if [[ -d "${PROJECT_ROOT}/.claude/agents" ]]; then
+  for legacy in "${PROJECT_ROOT}/.claude/agents/"*.md; do
+    [[ -L "$legacy" ]] && rm -f "$legacy"
+  done
+  rmdir "${PROJECT_ROOT}/.claude/agents" 2>/dev/null || true
+fi
+
+# 12. Local permission overrides — copy template once if not present.
+LOCAL_TEMPLATE="${CODING_OS_ROOT}/adapters/claude/settings.local.template.json"
+LOCAL_TARGET="${PROJECT_ROOT}/.claude/settings.local.json"
+if [[ ! -f "$LOCAL_TARGET" && -f "$LOCAL_TEMPLATE" ]]; then
+  cp "$LOCAL_TEMPLATE" "$LOCAL_TARGET"
+fi
+
+echo ""
+echo "✅ Claude adapter installed."
+echo "  Settings: .claude/settings.json (generated)"
+echo "  Perms:    .claude/settings.local.json (copied)"
+echo "  MCP:      .mcp.json (updated)"
+echo "  Roles:    .claude/commands/role-*.md (slash commands)"
+echo ""
+echo "Optional: real role-agent dispatch via claude-agent-sdk"
+echo "  uv sync --extra claude-sdk"
+echo "  # → cos_dispatch_formula_run spawns real Claude Code sub-sessions"
+echo "  # → see docs/adapters/claude-sdk.md"
+echo ""
+echo "Branding note:"
+echo "  This adapter integrates coding-os with Anthropic's Claude Code."
+echo "  coding-os is independent and is NOT branded as, affiliated with,"
+echo "  or endorsed by Anthropic. References to 'Claude Code' describe"
+echo "  Anthropic's product per their terms — see docs/adapters/claude-sdk.md."