Client Adapters

Adapters translate between AI agent wire formats and SigmaShake's internal ToolCall type. They also handle hook installation and capability classification.

Adapter interface

interface ClientAdapter {
  readonly name: string;
  detect(): boolean;
  parseInput(raw: string): ToolCall;
  formatOutput(result: EvalResult): string;
  toolCapability(toolName: string): Capability;
  install(projectDir: string): Promise<void>;
  uninstall(projectDir: string): Promise<void>;
  healthCheck(): Promise<boolean>;
}

Built-in adapters

Claude Code Adapter

Name: claude-code

Detection: Looks for CLAUDE_CODE_VERSION, CLAUDE_CODE_API_KEY, or CLAUDE_CODE_ENTRYPOINT environment variables.

Tool capability mapping: Hardcoded map for 30+ Claude Code tools:

• Bash → execute
• Read → read
• Write, Edit, MultiEdit → write
• Glob, Grep → search
• Agent → agent
• WebFetch, WebSearch → network

Hook installation: Uses ssg hook eval as a PreToolUse hook. Includes circuit breaker protection (auto-allow after 5 consecutive denies to prevent lockout).

Generic Adapter

Name: generic

Detection: Always matches (fallback).

Wire format:

{"tool": "toolName", "input": {"key": "value"}}

Capability classification: Keyword-based prefix matching on tool name.

Codex Adapter

Name: codex

Detection: SSG_CLIENT=codex environment variable.

Tool capability mapping:

• bash → execute
• shell → execute
• command → execute

Integration: Hybrid MCP + shell-wrapper. ssg init --client=codex installs:

• ~/.codex/config.toml — Registers the ssg-governance MCP server under [mcp_servers.ssg-governance]
• .ssg/bin/bash — A project-local shell wrapper used for enforced bash -c interception

The MCP registration gives Codex direct access to the SSG tools. The wrapper is still required for command-governance enforcement, because Codex does not expose native pre-tool-use hooks.

Setup:

ssg init --client=codex
SHELL=.ssg/bin/bash codex

Restart Codex after ssg init so it reloads ~/.codex/config.toml.

Codex Desktop Adapter

Name: codex-desktop

Detection: SSG_CLIENT=codex-desktop environment variable. This is deliberately distinct from the codex CLI adapter — both share ~/.codex/config.toml but the desktop variant uses the native [[hooks]] enforcement path added in the April 2026 Codex Desktop update.

Tool capability mapping:

Codex Desktop tool	Capability
bash, shell, local_shell, unified_exec, command	execute
apply_patch, update_plan	write
view_image, screenshot	read
web_search, in_app_browser	network
computer_use, click, type, key	execute

Integration: Three layers in one install — native hooks, MCP, project MCP:

• ~/.codex/config.toml → [[hooks]] entry — Pre-tool-use hook entry named ssg-governance. Codex Desktop runs ssg hook eval before every tool call and honours its allow/deny/ask decision. This is the cleanest enforcement surface in the Codex family.
• ~/.codex/config.toml → [mcp_servers.ssg-governance] block — Same MCP registration as the CLI adapter, gives the agent access to ssg_evaluate and the rest of the SSG MCP toolset.
• .codex/mcp.json (project-local) — Travels with the repo so a freshly-cloned project picks up the MCP server without re-running ssg init.

The CodexDesktop and Codex CLI adapters can be installed side-by-side without conflict — they write into separate sections of ~/.codex/config.toml and the strippers are content-addressed (the hook entry is detected by its name = "ssg-governance" field, not by marker comments).

Setup:

ssg init --client=codex-desktop  # writes [[hooks]] + [mcp_servers.ssg-governance]
# Restart Codex Desktop so it reloads ~/.codex/config.toml

Gemini CLI Adapter

Name: gemini

Detection: SSG_CLIENT=gemini environment variable.

Note: GEMINI_API_KEY is intentionally not used for detection — it is set by any application using the Gemini API and would cause false positives.

Tool capability mapping:

Gemini CLI tool	Capability
run_shell_command	execute
read_file	read
write_file, edit_file	write
search_files, list_files	search

Integration: Unlike the Pi adapter's shell-wrapper-only interception, the Gemini CLI adapter uses Gemini CLI's native TOML-based policy system. This provides full governance coverage across all 6 tool types — not just shell commands.

Policy installation: Creates .gemini/policies/ssg-governance.toml with baseline rules covering execution injection safety, file access restrictions, and telemetry control. Maps the 12 rules from the rules-gemini-cli hub ruleset into Gemini CLI's toolName/commandPrefix/commandRegex/decision/priority format.

Decision mapping:

SSG decision	Gemini CLI policy
DENY	deny
ASK	ask_user
ALLOW / LOG	allow
FORCE	deny

Priority mapping: SSG severity error=100, warning=50, info=10.

Setup:

ssg init --client=gemini       # generates .gemini/policies/ssg-governance.toml
ssg hub pull rules-gemini-cli  # add the full Gemini CLI security ruleset
gemini                          # start Gemini CLI — policies load automatically

Hub ruleset: The rules-gemini-cli hub ruleset provides 12 rules covering the critical vulnerabilities discovered after Gemini CLI's June 2025 launch: README prompt injection, eval injection bypass (GitHub #5495), GDPR non-compliant telemetry, and sandbox disable bypass.

Antigravity Adapter

Name: antigravity

Detection: ANTIGRAVITY_AGENT=1 environment variable.

Tool capability mapping:

• run_command, send_command_input, bash → execute
• view_file → read
• write_to_file, replace_file_content, multi_replace_file_content → write
• list_dir, grep_search → search
• read_url_content, search_web → network
• browser_subagent → agent

Integration Limitations: Unlike Claude Code or the Gemini CLI, the Antigravity agent does not currently natively support pre-tool hook configurations (e.g., settings.json or .toml policy manifests) inside its engine. As a result, the SSG antigravity adapter uses the shell wrapper fallback method (similar to the Pi and Codex adapters).

Warning: Full file I/O operations (such as write_to_file and view_file) execute natively within the Antigravity engine and bypass the shell wrapper completely. Only CLI shell operations routed through run_command or shell invocation are successfully captured and governed by SSG. You should structure your governance rules to focus on shell invocation integrity (e.g., preventing malicious execution) until native hooks are built for the agent.

Setup:

ssg init --client=antigravity # creates the .ssg/bin/bash wrapper
export SHELL=$PWD/.ssg/bin/bash
# Antigravity is now governed for shell commands

NemoClaw Adapter

Name: nemoclaw

Detection: SSG_CLIENT=nemoclaw, or the NEMOCLAW_AGENT / NEMOCLAW_SANDBOX_NAME environment variables that the nemoclaw CLI sets when launching a sandbox.

Tool capability mapping:

NemoClaw verb	Capability
process_exec, shell_exec, bash, shell	execute
fs_read, file_read	read
fs_write, file_write, fs_edit	write
net_egress, network_request, inference	network
sandbox_spawn	agent

Integration: NemoClaw runs every agent inside a hardened OpenShell sandbox with Landlock + seccomp + network namespaces and its own declarative YAML policy engine. SSG governance is complementary to that kernel-level isolation, not a replacement — it lives in the host-side ~/.nemoclaw/policies/ directory and is merged into every sandbox's baseline at launch time.

ssg init --client=nemoclaw installs:

• ~/.nemoclaw/policies/ssg-governance.yaml — A declarative policy fragment (schema: nemoclaw.policy/v1) covering filesystem.writable / readonly / deny, network.default = deny with an allowlist of common AI inference + package endpoints, and process.deny_privileged plus a deny list for mount, umount2, ptrace, init_module, etc.
• <ssg-hooks>/bin/bash — Host-side shell wrapper for defence-in-depth on the nemoclaw onboard / share mount paths that run outside the sandbox boundary.

Setup:

ssg init --client=nemoclaw                          # writes ~/.nemoclaw/policies/ssg-governance.yaml
nemoclaw <sandbox-name> policy-add \
  --file=~/.nemoclaw/policies/ssg-governance.yaml   # apply to an existing sandbox
ssg hub pull rules-nemoclaw                         # pull the full NemoClaw ruleset (optional)

Note: NemoClaw is in early preview (March 2026); the policy schema may evolve. The schema: nemoclaw.policy/v1 field pins the fragment to the v1 shape — re-run ssg init --client=nemoclaw after upgrading nemoclaw to regenerate against the current schema.

Claude Cowork Adapter

Name: claude-cowork

Detection: SSG_CLIENT=claude-cowork, or the CLAUDE_COWORK_VERSION environment variable (parallel to CLAUDE_CODE_VERSION for the terminal-native sibling). Detection is deliberately not triggered by the Claude Desktop app's mere presence — that app hosts both Cowork agent sessions and non-agent chat, and we don't want a chat session to fall under agent governance.

Tool capability mapping:

Cowork tool	Capability
bash	execute
read, screenshot, file_read	read
write, edit, multiedit, file_write	write
glob, grep	search
webfetch, websearch	network
computer_use, click, double_click, right_click, type, key, scroll, mouse_move, drag	execute

Cowork is distinct from Claude Code in that it adds a full computer-use surface — screen capture, mouse, keyboard — on top of the standard file + shell vocabulary. The capability map covers both surfaces plus the Open Cowork variant's file_read / file_write aliases.

Integration: Anthropic has not yet shipped a public PreToolUse hook API for Cowork (unlike Claude Code). The adapter therefore uses an MCP + governance-prompt approach:

• CLAUDE_COWORK.md (project-local) — A markdown governance prompt wrapped in <!-- SSG_GOVERNANCE_START --> / <!-- SSG_GOVERNANCE_END --> markers. Tells the model to call ssg_evaluate (via the MCP server below) before any tool call, including computer-use actions. Idempotently appended to any existing file.
• ~/.claude/mcp.json — Registers the ssg-governance MCP server under the user-scoped Claude Desktop config. Other MCP servers in the file are preserved.

Setup:

ssg init --client=claude-cowork  # creates CLAUDE_COWORK.md + ~/.claude/mcp.json entry
# Restart Claude Desktop so Cowork loads the ssg-governance MCP server

Note: as Cowork's hook surface matures, the install path will gain a native PreToolUse hook entry (the same shape as the Claude Code adapter). The MCP layer keeps working either way.

Cursor Adapter

Name: cursor

Detection: Checks for CURSOR_SESSION_ID environment variable or the ~/.cursor/ directory.

Tool capability mapping:

Cursor tool	Capability
run_terminal_command	execute
edit_file, create_file	write
read_file	read
codebase_search, grep_search, file_search, list_dir	search
web_search, fetch	network

Integration: MCP-based, identical to the Copilot adapter architecture. ssg init --client=cursor writes two files:

• .cursor/mcp.json — Registers the ssg-governance MCP server. Merges with any existing servers in that file.
• .cursor/rules/ssg-governance.mdc — A Cursor rule file with alwaysApply: true that instructs the agent to call ssg_evaluate before every tool use.

Setup:

ssg init --client=cursor    # creates .cursor/mcp.json + .cursor/rules/ssg-governance.mdc
# Restart Cursor to load the MCP server

Token cost: By default the MCP server exposes only the 4 core governance tools (~428 tokens). Use SSG_MCP_TOOLS in your .cursor/mcp.json env block to opt-in to more:

{
  "mcpServers": {
    "ssg-governance": {
      "command": "ssg",
      "args": ["mcp-server"],
      "env": {
        "SSG_CLIENT": "cursor",
        "SSG_MCP_TOOLS": "onboarding"
      }
    }
  }
}

See MCP Server → Token Budget for the full breakdown.

---

Adapter selection

Priority order:

1. SSG_CLIENT environment variable (explicit override)
2. Known client environment variables (e.g., CLAUDE_CODE_VERSION)
3. Generic adapter (fallback)

Creating custom adapters

Implement the ClientAdapter interface and register it in the adapter registry. Key considerations:

• detect() should be fast — it runs on every eval
• parseInput() must handle malformed input gracefully
• toolCapability() should cover all tools the client uses
• install() should be idempotent (safe to run multiple times)

Simulation testing

ssg certify validates governance rules by replaying synthetic scenarios through the full adapter path. Scenarios use Claude Code wire format (tool_name/tool_input) — the same format the PreToolUse hook sends — and assert the expected decision for each tool call.

The certify engine applies the same transformation as ssg hook eval:

{tool_name, tool_input}  →  {tool, input}  →  evaluate()

This means certification tests:

• The jq wire format transformation
• The ClaudeCodeAdapter.TOOL_MAP capability mapping
• The evaluation engine's decision logic against real rules

Run certification before publishing a ruleset:

ssg certify --dir=.sigmashake/scenarios

See Certification for the full scenario format and report submission.