optimus-tool-call

Passive, non-blocking audit sensor for tool calls from coding agents (Claude Code, Cursor, GitHub Copilot, etc.).

Features

• 50+ command classifiers - Full nah taxonomy coverage
• 40+ action types - Comprehensive security categorization
• Real-time telemetry - Async event streaming to backend
• Zero developer friction - <50ms p99 latency, never blocks execution
• Smart parsing - Handles pipes, redirects, command chains, shell builtins
• Flag-based detection - Context-aware classification (sed -i, curl -X POST, make --dry-run, etc.)

How It Works

1. Hook Integration: Integrates with Claude Code PreToolUse hooks
2. Command Classification: Parses and classifies each tool call into an action type
3. Telemetry Event: Creates event with classified action, file paths, session info
4. Async Streaming: Non-blocking queue sends events to backend in batches
5. Backend Severity: Django backend assigns severity (critical/high/medium/low/info)
6. Frontend Dashboard: Real-time audit log with 2-second polling

Installation

npm install @optimus/tool-call

Usage

Via PreToolUse hook (automatic in Claude Code):

{
  "preToolUse": {
    "matcher": "*",
    "command": "node path/to/optimus-tool-call/dist/index.js"
  }
}

The hook:

• Classifies the tool call
• Extracts relevant metadata (files, commands, patterns)
• Queues telemetry event
• Returns {"continue": true, "permission": "allow"} (never blocks)

Command Coverage

See COMMAND_COVERAGE.md for complete list of 50+ supported commands and their classifications.

Quick Examples

Filesystem:
  read:   cat, grep, ls, find, head, tail, which
  write:  echo, touch, mkdir, cp, mv, chmod
  delete: rm

Git:
  safe:           log, status, diff, branch
  write:          add, commit, checkout, pull
  history_rewrite: push --force, reset --hard, rebase

Network:
  outbound: curl, wget, ssh
  write:    curl --data, scp, rsync

Language Execution:
  python, node, ruby, bash, source, gdb

Text Processing:
  sed -i → filesystem_write
  awk with system() → lang_exec

And 30+ more...

Action Types

| Type | Examples | Severity | |------|----------|----------| | filesystem_read | cat, grep, ls, find, head | low | | filesystem_write | echo, touch, mkdir, cp, mv | medium | | filesystem_delete | rm | medium | | git_safe | git log, git status | low | | git_write | git add, git commit | medium | | git_remote_write | git push | medium | | git_discard | git branch -d | medium | | git_history_rewrite | git push --force, git rebase | critical | | network_outbound | curl GET, wget | low | | network_write | curl POST, scp, rsync | high | | network_diagnostic | ping, traceroute | low | | package_install | npm install, pip install | high | | package_run | npm run | medium | | lang_exec | python, node, bash, gdb | high | | process_signal | kill, pkill | high | | container_read | docker ps, docker logs | low | | container_write | docker build, docker create | medium | | container_exec | docker run, docker exec | medium | | container_destructive | docker rm, docker stop | high | | service_write | systemctl start, service restart | high | | agent_exec_bypass | (reserved for future) | critical | | obfuscated | (reserved for future) | critical |

Configuration

Environment variables (optional):

OPTIMUS_API_URL=https://your-host/             # Backend base URL (same as log-llm-config; see optimus-tofu)
OPTIMUS_ENDPOINT=...                          # Alternative to OPTIMUS_API_URL
OPTIMUS_HARDWARE_UUID=...                     # Override when no stable hardware UUID (e.g. Linux CI)
OPTIMUS_BATCH_SIZE=50                         # Batch size before flush (default: 1 for testing, 50 for prod)
OPTIMUS_DEBUG=1                               # Verbose stderr (payload preview, endpoint, HTTP details)
OPTIMUS_TOOL_CALL_LOG=1                       # One line per successful batch on stderr: host, path, status, count

Hook wrappers append stderr to ~/.cursor/hook-errors.log or ~/.claude/hook-errors.log, so enable OPTIMUS_TOOL_CALL_LOG or OPTIMUS_DEBUG in ~/opt-ai-sec/management/optimus_dev.env (the hook exports these from that file).

Ingestion uses the same machine auth as log-llm-config: keys under ~/opt-ai-sec/management/auth_key.txt, handshake against /endpoint_security/auth/, and HMAC signatures on each batch (see backend batch_create).

Architecture

┌─────────────────────────────────────────────┐
│ Coding Agent (Claude Code, Cursor, etc.)    │
└────────────────────┬────────────────────────┘
                     │ PreToolUse hook
                     ▼
┌─────────────────────────────────────────────┐
│ optimus-tool-call (TypeScript)              │
│ ├─ Classify command into action type        │
│ ├─ Extract file paths, patterns, etc.       │
│ ├─ Create telemetry event                   │
│ └─ Queue for async streaming                │
└────────────────────┬────────────────────────┘
                     │ Non-blocking async
                     ▼
┌─────────────────────────────────────────────┐
│ Django Backend (optimus_security)           │
│ ├─ Receive batched events                   │
│ ├─ Calculate severity                       │
│ ├─ Store in SQLite                          │
│ └─ Expose via REST API                      │
└────────────────────┬────────────────────────┘
                     │ /api/tool-calls/events/recent/
                     ▼
┌─────────────────────────────────────────────┐
│ Frontend Dashboard (React)                  │
│ ├─ Real-time audit log (2s polling)         │
│ ├─ Color-coded severity/agent               │
│ └─ Expandable command details               │
└─────────────────────────────────────────────┘

Development

npm install
npm run build
npm run test

Testing

E2E test with various commands:

./test-e2e.sh

This will:

1. Clear the audit log
2. Run 50+ diverse commands (filesystem, git, network, package, etc.)
3. Verify correct classification for each
4. Display coverage summary

Performance

• Classification latency: <1ms per command
• Telemetry overhead: <50ms p99 (async, non-blocking)
• Memory: ~10MB resident (minimal buffering)
• CPU: Negligible (event-driven)

Safety

• ✅ Never blocks agent execution
• ✅ Always returns permission: "allow"
• ✅ Errors logged but never thrown
• ✅ Graceful degradation if backend unavailable
• ✅ Batch timeout ensures events flush (5s default)

References

• Based on nah taxonomy: https://github.com/manuelschipper/nah
• Integrated with Optimus Labs security platform
• Part of agent compliance and audit infrastructure