# 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

```bash
npm install @optimus/tool-call
```

## Usage

Via PreToolUse hook (automatic in Claude Code):

```json
{
  "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](./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):

```bash
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

```bash
npm install
npm run build
npm run test
```

## Testing

E2E test with various commands:

```bash
./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