smart-approve

A custom "bash" tool that replaces OMP's built-in bash, with LLM-powered risk analysis, behavior detection, protected-path interception, and decision memory. Compatible with both oh-my-pi (OMP) and upstream pi-agent.

Safe commands pass through with zero interruption. When a dangerous behavior is detected, the custom tool's execute() method runs LLM risk analysis and shows an approval dialog — all outside OMP's 30-second EXTENSION_HANDLER_TIMEOUT_MS, so there is no time pressure. In headless (subagent) contexts, dangerous operations are blocked outright.

How it works

LLM calls bash tool
       │
   analyzeCommand() — argument parsing + regex secondary net
       ├─ hard-block (rm -rf /, fork bomb, curl|sh…) → block always
       ├─ no behaviors → execute (zero interruption)
       └─ dangerous behavior → needs review ↓
              │
          allow-list hit (session or permanent)? ── yes → execute
              │ no
          ctx.hasUI === false (headless) → block
              │ has UI:
              setStatus("analyzing…")
              gatherSessionContext() — original user task + recent agent plan
              RPC prompt → @tiny (bounded by analysisTimeoutMs)
                  @tiny fails/times out? → @smol → @default (each bounded)
                  success → dialog shows risk / summary / detail / recommendation
                  failure → dialog shows rule-based label only
              ctx.ui.select(title, [session allow, permanent allow, deny])
                  session   → in-memory Set (cleared on restart)
                  permanent → persisted to JSON file
                  deny      → block
              approved → ctx.invokeTool() delegates to native bash tool → return output to LLM

Hard-block wins over the allow-list: an entry that predates a rule upgrade (or was hand-edited into smart-approve-allow.json) can never bypass a hard-block.

write/edit to protected paths is handled separately via the tool_call hook — pure path matching + confirmation dialog, no LLM analysis (the path itself is sufficient signal).

Architecture: custom tool, not handler interception

OMP's EXTENSION_HANDLER_TIMEOUT_MS (30s, hardcoded) wraps tool_call event handler dispatch — but not custom tool execute() methods. This extension exploits that:

1. pi.registerTool({ name: "bash", ... }) — registers a replacement with the same name, shadowing the built-in
2. All approval logic (behavior detection → LLM analysis → ui.select → execution) lives inside execute(), free from the 30s timeout
3. Execution is delegated to the native bash tool via ctx.invokeTool(), inheriting shell path resolution, env hardening, PTY, and output truncation

The previous architecture intercepted bash via pi.on("tool_call") and was killed by the 30s timeout during LLM analysis. The custom tool architecture eliminates this entirely.

LLM risk analysis: persistent RPC session

Risk analysis does not cold-start a new omp -p subprocess per call. Instead, the extension spawns one omp --mode rpc child on first use and reuses it over a JSONL stdio protocol for every analysis in the session:

• One process, many prompts — extension loading (including provider-retry-proxy) and process startup are paid once per host session, not per analysis
• Per-attempt timeout — each prompt is bounded by analysisTimeoutMs (default 30s, 0 = no timeout); a hung remote model cannot freeze the bash tool
• Model fallback chain — @tiny first (cheapest), then @smol, then @default; each attempt time-bounded; total failure degrades to rule-label confirmation
• Interruption — the tool's AbortSignal is forwarded to the RPC child (abort command), so a user interrupt cancels an in-flight analysis instead of leaving it running
• Lifecycle — the child is lazily spawned on first use, killed via session_shutdown, reaped after rpcIdleTimeoutMs (default 10 min) of inactivity, and exits on its own if the host dies (stdin EOF closes → process exits code 0, no orphans)

The LLM receives:

• Session context — original user task + recent agent plan (injection-guarded)
• Detected behaviors — localized labels
• The command — as-is

And returns structured JSON: risk (low/medium/high), summary, detail, recommend.

Features

1. Behavior-based detection (not just regex)

Parses git arguments to detect behaviors that regex alone misses:

Command	Behavior detected	How
git push origin +main	force-push	+refspec, not just --force
git branch -D feature	branch-delete	combined short flags like -rD
git clean -fd	git-clean	--dry-run excluded
git reset --hard	hard-reset	--hard flag
git worktree remove	worktree-remove	subcommand parsing

Regex rules remain as a secondary net covering 30+ patterns: rm -rf (case-insensitive, including -Rf/-RF and --recursive --force), fork bombs, curl|sh, mkfs, dd, kill -9, sudo, docker rm, kubectl delete, 20+ git destructive operations, and more.

2. Protected path interception (write/edit)

Intercepts write/edit tool calls via the tool_call hook and matches the target path against glob patterns:

• .env, .env.* (.env.example explicitly allowed)
• **/.ssh/**, **/.kube/config, **/.aws/credentials
• **/.git-credentials, **/.netrc, **/.npmrc, **/.pypirc
• **/id_rsa, **/id_ed25519, **/*.pem, **/*.key, **/*.p12, **/*.kdbx
• **/auth.json, **/.config/gh/hosts.yml, **/.config/gcloud/**

Matching is symlink-aware: resolves realpath before matching, so a symlink alias can't evade a deny.

Path matching is pure and fast — no LLM analysis needed. The 30s handler budget is more than sufficient for path matching + confirmation dialog.

3. Decision memory

The confirmation dialog offers three choices:

Option	Storage	Lifetime
Allow for this session	In-memory Set<string>	Cleared on restart
Always allow	~/.omp/agent/smart-approve-allow.json	Persists across restarts
Deny	—	Blocks the command

Keys are scoped to tool + normalized-content + cwd, so the same command in a different project still triggers review. When the UI doesn't support select, it degrades to a simple confirm (two-way).

4. Session context for LLM review

Reads the agent's conversation history via ctx.sessionManager.getBranch() / getEntries() and extracts:

• Original user task — the first user message (truncated to 1000 chars)
• Recent agent plan text — the last 2 assistant text blocks (each truncated to 800 chars)

All context is wrapped in <untrusted_context> blocks with injection guards. Tool outputs and tool-call arguments are explicitly excluded (largest injection surface). When sessionManager is unavailable, it safely degrades to null — LLM review still works, just without context.

5. Hard-block behaviors

The following behaviors are always hard-blocked — no LLM review, no dialog, no allow-list override:

• Delete root path (rm -rf /)
• Fork bombs
• Remote fetch-and-execute (curl|sh)
• Writes to /etc/passwd, /etc/shadow, /etc/sudoers, /etc/hosts
• Writes to raw block devices (/dev/sd*, /dev/nvme*, …)
• Disk format (mkfs, dd to block device)
• Shutdown / reboot

6. Execution via native bash tool delegation

Commands are never executed directly by the extension. After passing the approval gate, execution is delegated to OMP's built-in bash tool via ctx.invokeTool(). This inherits all native behavior:

• Shell path resolution — no ENOENT from missing PATH in worker processes
• PTY support — interactive commands work when the native tool uses PTY
• Env hardening — PAGER=cat, GIT_TERMINAL_PROMPT=0, etc.
• Output truncation — head/tail windows with artifact spill
• Cross-platform — no hardcoded binary paths

7. OMP + pi dual compatibility with graceful degradation

Aspect	Implementation
Dual manifest	package.json declares both omp.extensions and pi.extensions
Host detection	process.execPath → process.argv[1] → PATH lookup (omp → pi)
LLM invocation	Persistent omp --mode rpc / pi --mode rpc child, JSONL over stdio
Model fallback	@tiny → @smol → @default (each time-bounded) → rule-only confirmation (no LLM)
Headless	ctx.hasUI === false blocks all dangerous operations immediately
Bilingual	zh/en, auto-adapts to locale (LC_ALL > LC_MESSAGES > LANG > macOS AppleLocale)

Install

npm install smart-approve

Then configure OMP to load the extension:

# ~/.omp/agent/config.yml   (or ~/.pi/agent/config.yml for pi-agent)
extensions:
  - smart-approve
tools:
  approvalMode: yolo

• tools.approvalMode: yolo — auto-approve safe commands; this extension is the sole gate for dangerous ones
• extensions: [smart-approve] — load the extension from node_modules

The custom "bash" tool shadows the built-in by name — no bash.enabled change is needed. Restart the host after installing or editing.

Configuration

Config lives at ~/.omp/agent/smart-approve.json (or ~/.pi/agent/smart-approve.json on pi-agent). All fields are optional — defaults apply when missing:

{
  "enabled": true,
  "protectedPaths": [
    ".env", ".env.*", "!.env.example",
    "**/.ssh/**", "**/.kube/config", "**/.aws/credentials",
    "**/*.pem", "**/*.key", "**/*.p12", "**/*.kdbx",
    "**/id_rsa", "**/id_ed25519", "**/auth.json"
  ],
  "llmAnalysis": true,
  "rememberDecisions": true,
  "contextMaxChars": 3000,
  "analysisTimeoutMs": 30000,
  "rpcIdleTimeoutMs": 600000,
  "model": "@tiny"
}

Field	Default	Description
enabled	true	Master switch
protectedPaths	20+ built-in patterns	Glob patterns for write/edit interception; ! prefix negates
llmAnalysis	true	Whether to invoke the model for risk analysis; false = rule-only confirmation
rememberDecisions	true	Whether to offer session/permanent remember options in the dialog
contextMaxChars	3000	Max chars of session context to feed the LLM
analysisTimeoutMs	30000	Per-attempt timeout for the RPC risk-analysis prompt in ms; 0 = no timeout. On timeout/failure the model chain advances @tiny → @smol → @default, then rule-label confirmation
rpcIdleTimeoutMs	600000	Idle lifetime of the persistent RPC child in ms; 0 = keep alive until session end. After this long without a prompt the child is killed (frees its memory) and lazily respawned on the next analysis
model	@tiny	Model spec for risk analysis (role alias, provider/id, or bare id). Attempt chain: configured model runs first, then @tiny → @smol → @default as fallbacks (deduped)

Allow-list (decision memory)

Permanent allow entries are stored at ~/.omp/agent/smart-approve-allow.json:

{
  "permanent": [
    {
      "tool": "bash",
      "key": "git push origin main",
      "cwd": "/home/user/myproject",
      "timestamp": "2026-07-23T05:00:00.000Z"
    }
  ]
}

Session allows are in-memory only, cleared on restart. You can edit or delete this file to revoke remembered decisions.

Extension API surface used

API	Purpose
pi.registerTool({ name, parameters, execute })	Register custom "bash" tool shadowing the built-in
pi.zod	Injected zod module for tool parameter schemas
ctx.invokeTool(params, opts)	Delegate execution to native bash tool
child_process.spawn(hostBin, ["--mode", "rpc", ...])	Persistent RPC child for LLM risk analysis
pi.on("tool_call", handler)	Intercept write/edit on protected paths
ctx.hasUI	Detect headless/subagent context
ctx.sessionManager.getBranch() / getEntries()	Gather session context for LLM review
ctx.ui.setStatus(id, text)	Show "analyzing…" status
ctx.ui.confirm(title, body)	Confirmation dialog (fallback when select unavailable)
ctx.ui.select(title, choices)	Three-way choice: session allow / permanent allow / deny
return { block: true, reason }	Block contract for tool_call handler (write/edit only)

Project layout

smart-approve/
├── README.md
├── package.json          ← omp.extensions / pi.extensions manifest (v2.4.4)
├── LICENSE               ← MIT
├── src/
│   ├── index.ts          ← SmartApprove orchestrator: register bash tool + write/edit hook
│   ├── bash-tool.ts      ← custom "bash" tool (shadows built-in, delegates via ctx.invokeTool)
│   ├── types.ts          ← ExtensionAPI, ToolDefinition, AgentToolResult, etc.
│   ├── host.ts           ← HostResolver + ModelInvoker (persistent RPC LLM analysis)
│   ├── rpc-invoker.ts    ← RPC client: spawn/reuse/kill omp --mode rpc child
│   ├── behaviors.ts      ← behavior catalog, git parser, composite analysis
│   ├── paths.ts          ← ProtectedPathMatcher (symlink-aware)
│   ├── config.ts         ← ConfigStore
│   ├── allowlist.ts      ← AllowList (session + permanent)
│   ├── context.ts        ← SessionContextGatherer
│   ├── dialog.ts         ← confirmWithRemember + formatAnalysis
│   ├── i18n.ts           ← locale detection + bilingual strings (zh/en)
│   └── logger.ts         ← Logger (file + stderr)
└── dist/
    └── index.js          ← bundled output (bun build, ~50KB)

Runtime artifacts

~/.omp/agent/smart-approve.json          — config (user-editable)
~/.omp/agent/smart-approve-allow.json    — permanent allow-list (auto-maintained)
~/.omp/logs/smart-approve.log            — diagnostic log

License

MIT