KeiSeiKit-1.0/docs/encyclopedia/cross-cli-policy.md

# Cross-CLI policy enforcement

> *Same safety rules. Any LLM CLI. Three honesty tiers.*

KeiSeiKit's safety hooks (`no-github-push`, `safety-guard`, `destructive-guard`,
`citation-verify`, `numeric-claims-guard`) originally fired only inside Claude
Code's `PreToolUse` pipeline. Phase C extends enforcement to other CLIs —
but the strength of enforcement depends on what each CLI permits.

## The 3-tier honesty model

| Tier | What it means | CLIs |
|---|---|---|
| **TIER 1 — full native** | Tool-call enforcement at the CLI's own hook layer. Same as Claude. | claude, **grok** |
| **TIER 2 — MCP-wrapped** | Native shell disabled at launch; agent forced to use our policy-gated `kei_bash`/`kei_edit`/`kei_write` MCP tools. | **copilot** |
| **TIER 3 — advisory** | CLI can't disable native shell; we register kei-mcp and instruct the agent to prefer `kei_*` tools, but enforcement is prompt-level only. | **agy, kimi** |

For patent-sensitive or production-PR work — stick to TIER 1 (claude or grok).

## How to wire

One command sets up enforcement for whichever CLIs you have installed:

```bash
kei mcp-wire                    # detect + wire all installed CLIs
kei mcp-wire grok               # wire one CLI
kei mcp-wire --dry-run          # preview config changes without writing
kei mcp-wire --list             # show enforcement tier per CLI
```

The orchestrator is idempotent — running twice produces the same config.

## What `kei mcp-wire` writes

### claude (TIER 1 — already enforced)
No-op. Native PreToolUse hooks already gate every tool call. `kei mcp-wire claude`
prints the optional `mcpServers` snippet you can add to
`~/.claude/settings.json` if you want claude to also see `spawn_agent` for
sub-agent dispatch.

### grok (TIER 1 — port our hooks)
Writes `~/.grok/settings.json` `hooks.PreToolUse` block:

- `Bash` matcher → `no-github-push.sh` + `safety-guard.sh` + `destructive-guard.sh`
- `Edit` matcher → `citation-verify.sh` + `numeric-claims-guard.sh`
- `Write` matcher → `citation-verify.sh` + `numeric-claims-guard.sh`

Plus registers kei-mcp with `GROKCODE=1` env (so kei-mcp's policy chain skips
duplicate enforcement when invoked via Grok — your native hooks already fired).

xAI's Grok uses the same JSON input contract as Claude Code's PreToolUse, so
our hook scripts run unchanged. Identical enforcement to claude.

### copilot (TIER 2 — disable native shell, force MCP)
Writes `~/.copilot/mcp-config.json` registering kei-mcp. To activate enforcement,
launch copilot with `--excluded-tools='shell'`:

```bash
alias copilot='copilot --excluded-tools=shell'
```

The agent will have NO native shell tool, only kei-mcp's `kei_bash` —
which runs the policy chain before execution. `kei_edit` / `kei_write`
similarly gate file mutations.

### agy / kimi (TIER 3 — advisory)
Writes their MCP config (`~/.gemini/config/mcp_config.json` for agy,
`~/.kimi/mcp.json` for kimi) registering kei-mcp.

**The honest part:** these CLIs do NOT have a way to disable their native
shell. The agent CAN reach for native bash regardless of what we tell it.
The system prompt nudges it toward `kei_bash`, but a determined or careless
agent can bypass.

For patent-sensitive work — **don't use agy or kimi as orchestrator**.
Use them for analysis / brainstorming / no-side-effect tasks only.

## Internals

### policy-chain.toml (SSoT)

One file declares which hooks gate which tool, for all CLIs that go through
the MCP layer:

```toml
# ~/.claude/hooks/_lib/policy-chain.toml
[bash]
chain = ["no-github-push.sh", "safety-guard.sh", "destructive-guard.sh"]

[edit]
chain = ["citation-verify.sh", "numeric-claims-guard.sh"]

[write]
chain = ["citation-verify.sh", "numeric-claims-guard.sh"]
```

To add a hook: append its basename. The hook script must already exist in
`~/.claude/hooks/` and follow the standard PreToolUse contract (read JSON
on stdin with `.tool_name` + `.tool_input`, return exit 0 = pass / 2 = block).

### kei-mcp built-in tools

`kei-mcp` (Rust MCP server at `_primitives/_rust/kei-mcp/`) exposes 4
built-in tools across two source files (both bypass the atom-discovery
loop in `handlers/tools.rs`):

In `handlers/tools.rs`:
- `spawn_agent(name, task, on?)` — invokes a KeiSeiKit agent on any backend

In `handlers/safe_tools.rs` (Phase C, v0.40+):
- `kei_bash(command, cwd?)` — runs `[bash]` chain → executes
- `kei_edit(file_path, old_string, new_string)` — runs `[edit]` chain → edits
- `kei_write(file_path, content)` — runs `[write]` chain → writes

The chain runs against the same hook scripts Claude uses; identical input
shape, identical decisions. On block, the hook's stderr surfaces as the MCP
error message so the calling agent sees exactly why.

**v0.42 hardening** (post 4-CLI re-audit, supersedes v0.41):

- **Fail-CLOSED everywhere** — missing config, missing hook, OR empty
  section (`[bash]/[edit]/[write]` with no entries) all refuse to run.
  Tests / dev can opt in via `KEI_POLICY_CHAIN_OPTIONAL=1`.
- **Symlink-safe path guard** — `kei_edit` / `kei_write` canonicalize the
  FULL path (resolving any leaf symlink to its real target) and reject
  if the leaf itself is a symlink for a not-yet-existent file. Fixes the
  v0.41 CRITICAL bypass where `ln -s ~/.ssh/keys ./x; kei_write x` would
  follow the link.
- **$PWD-only default root** — `allowed_roots` defaults to current working
  directory only. Was: `$PWD` + entire `$HOME` — too permissive, agent
  could overwrite `~/.claude/hooks/*` (self-neuter) or `~/.zshrc` (RCE on
  next shell). Operators who need broader access set `KEI_ALLOWED_ROOTS`.
- **Denylist extended** — system dirs (`/etc/`, `/usr/`, `/System/`,
  `/var/`, `/root/`, `/bin/`, `/sbin/`); credential stores (`~/.ssh/`,
  `~/.aws/`, `~/.gnupg/`, `~/.config/gcloud/`, `~/.cargo/credentials`,
  `~/.docker/config.json`, `~/.kube/`); substrate dirs (`~/.claude/`,
  `~/.grok/`, `~/.gemini/`, `~/.copilot/`, `~/.kimi/`); exact shell-init
  files (`.zshrc`, `.bashrc`, `.profile`, `.zshenv`, `.gitconfig`, ...).
- **Async file I/O in load_chain** — `policy-chain.toml` now read via
  `tokio::fs` (was: blocking `std::fs` froze worker on slow mounts).
- **Process-group kill on hooks too** — hook subprocesses get
  `process_group(0)` and `killpg(SIGKILL)` on timeout. Was: only the bash
  action got this; hook grandchildren orphaned.
- **CLAUDECODE/GROKCODE design note** — documented as perf/UX
  optimization, NOT a security boundary (env-controllable parent → confused
  deputy is already-game-over scenario).

### Double-enforcement guard

If kei-mcp is invoked from a process where `$CLAUDECODE=1` or `$GROKCODE=1`,
it SKIPS its hook chain — the CLI's native hooks already fired. This is set
automatically by `kei mcp-wire claude` / `kei mcp-wire grok`. On copilot /
agy / kimi the env is unset → chain runs.

## Verification

```bash
# All 4 built-ins must list:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | kei-mcp | jq -r '.result.capabilities'

# Block test (kei_bash refuses forbidden command):
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kei_bash","arguments":{"command":"git push https://github.com/x/y.git main"}}}' \
  | kei-mcp 2>&1 | grep "RULE 0.1"   # expects: BLOCK — RULE 0.1 NO GITHUB PUSH

# Pass test:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"kei_bash","arguments":{"command":"echo OK"}}}' \
  | kei-mcp | tail -1 | jq -r '.result.content[0].text'   # expects: OK
```

## Related

- [Multi-CLI agent invocation](./multi-cli-agents.md) — DNA-resolved agent dispatch
- `kei-mcp` source: `_primitives/_rust/kei-mcp/src/handlers/safe_tools.rs`
- Policy SSoT: `hooks/_lib/policy-chain.toml`
- Wire scripts: `scripts/kei-mcp-wire*.sh`