RFC: deterministic pre-execution guardrails for terminal commands (Grimdall hook)

[grimdalltech]

Summary

Propose an opt-in hook that wraps CodeCompanion's command-execution / tool-approval flow to add deterministic, below-the-model guardrails: block destructive commands, deny reads of secret files, and enforce an egress allowlist. Shadow-mode (log-only) by default — zero behavior change unless enabled.

Motivation

CodeCompanion runs commands and reads/writes files directly in the user's environment with the user's credentials. Today the safety boundary is the user approving each action in the Neovim UI. That boundary disappears in agent mode and non-interactive automation, where there's no deterministic check between the model's output and the shell — the classic "confused deputy" problem.

Proposed integration (corrected)

The seam is the command-execution / tool-approval flow, not the adapter layer. A single Lua module wraps that path so that, before a command runs, it:

1. Shell policy — AST-parse the command and block destructive patterns (rm -rf, DROP TABLE, chmod -R 000, fork bombs, etc.).
2. Secret-read denial — refuse reads of ~/.ssh, ~/.aws, .env, *.pem.
3. Egress allowlist — deny network egress not on an explicit allowlist.

Default is shadow mode: log what it would block, enforce only when enabled.

Rough Lua sketch

local grimdall = require("codecompanion.grimdall") -- or a companion plugin

--- Called before command execution / tool approval.
--- Returns (allow, reason)
local function guard(cmd)
  local v = grimdall.check(cmd) -- { allow: boolean, reason: string, mode: "shadow"|"enforce" }
  if v.mode == "shadow" then
    vim.notify("grimdall (shadow) would block: " .. v.reason, vim.log.levels.WARN)
    return true
  end
  if not v.allow then
    vim.notify("grimdall blocked: " .. v.reason, vim.log.levels.ERROR)
    return false, v.reason
  end
  return true
end

-- Wire into the command-execution / tool-approval path here (exact seam TBD).

grimdall.check() shells out to grimdall-os (MIT, <2ms) and returns a structured allow/deny with a reason. The plugin stays opt-in and shadow-mode by default.

Non-goals

• No core changes; additive wrapper.
• Opt-in; no behavior change by default.

Happy to open a PR with the module + tests once the exact command-execution seam is confirmed.