orchestrata_ultimate.drivers.claude_settings

Reference › orchestrata_ultimate › drivers › claude_settings

claude_settings generates the Claude Code settings file that wires the SPEC-025 governance gate. write_governance_settings writes .claude/orchestrata-settings.json inside a workspace and returns its path. The settings (built by _build_settings) register a PreToolUse hook that runs scripts/claude_governance_gate.py from the repository root, which gates every Claude Code tool call through the real tool interceptor in the core Claude adapter. The module only produces the file; claude_code_driver passes the path to the CLI with --settings. Tests are in tests/drivers/test_claude_settings.py.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/drivers/claude_settings.py

# mypy: ignore-errors
"""Claude Code settings generation for the SPEC-025 governance gate.

``write_governance_settings`` writes a per-workspace
``.claude/orchestrata-settings.json`` wiring a ``PreToolUse`` hook that
shells out to ``scripts/claude_governance_gate.py`` (Phase 2b) — the shim
that gates every Claude Code tool call through the real
``ToolInterceptor`` (``orchestrata_ultimate.core.adapters.claude.tool_interceptor``).

``ClaudeCodeDriver`` (Phase 1) forwards this file's path to the ``claude``
CLI via ``--settings`` when ``ORCHESTRATA_CLAUDE_SETTINGS`` is set in its
env mapping; this module only produces the file, it does not invoke the
CLI itself.
"""

from __future__ import annotations

import json
import os
from collections.abc import Mapping

from orchestrata_ultimate.core.traceability import traces

_SETTINGS_RELATIVE_PATH = os.path.join(".claude", "orchestrata-settings.json")
_GATE_SCRIPT_RELATIVE_PATH = os.path.join("scripts", "claude_governance_gate.py")


@traces(spec="025", reqs=["REQ-025-097"])
def _build_settings(repo_root: str) -> dict:
    """Build the settings dict wiring the PreToolUse governance gate.

    Args:
        repo_root: Absolute path to the orchestrata-ultimate repo root, used
            to build the ``uv run --project`` invocation of the gate shim.

    Returns:
        A JSON-serializable settings dict (Claude Code hooks schema).
    """
    gate_script = os.path.join(repo_root, _GATE_SCRIPT_RELATIVE_PATH)
    command = f"uv run --project {repo_root} python {gate_script}"
    return {
        "hooks": {
            "PreToolUse": [
                {
                    "matcher": "*",
                    "hooks": [
                        {
                            "type": "command",
                            "command": command,
                        }
                    ],
                }
            ]
        }
    }


@traces(
    spec="025",
    reqs=["REQ-025-097"],
)
def write_governance_settings(
    workspace: str,
    repo_root: str,
    env: Mapping[str, str] | None = None,
) -> str:
    """Write ``<workspace>/.claude/orchestrata-settings.json`` and return its path.

    Pure/idempotent: calling this repeatedly with the same arguments
    overwrites the file with byte-identical (sorted-key) content.

    Args:
        workspace: Target Claude Code workspace directory.
        repo_root: Absolute path to the orchestrata-ultimate repo root — used
            to build the ``uv run --project <repo_root> python
            <repo_root>/scripts/claude_governance_gate.py`` hook command.
        env: Unused by the write itself; accepted for the project's uniform
            env-injection seam (``os.environ.get`` through an injected
            mapping) and for callers that want to pass one through
            uniformly. Reserved for future env-driven variants.

    Returns:
        Absolute path to the written settings file.
    """
    del env  # not currently needed; kept for seam consistency, see docstring.

    settings_dir = os.path.join(workspace, ".claude")
    os.makedirs(settings_dir, exist_ok=True)
    settings_path = os.path.join(settings_dir, "orchestrata-settings.json")

    settings = _build_settings(repo_root)
    with open(settings_path, "w", encoding="utf-8") as fh:
        json.dump(settings, fh, indent=2, sort_keys=True)
        fh.write("\n")

    return settings_path