Runtime Architecture

Lifecycle Hooks Specification

How jev-superpowers binds process-level interceptors to agent execution loops to enforce deterministic boundaries before code is run or committed.

The 3 Enforcement Gates

Unlike text-based guardrails that rely on prompt compliance, lifecycle hooks execute in the operating system shell prior to tool invocation.

Gate 1: PreToolUse (Command & Dependency Interceptor) Pre-Execution

Fires before the agent harness executes bash, read, write, or edit tool calls. If the command attempts to add a crate or npm package, jev-scout evaluates the package name against live registry registries. If the command attempts a destructive delete, jev-guard blocks it unless confidence >= 0.80.

// Claude Code hooks.json configuration
{
  "PreToolUse": [
    {
      "matcher": "tool_name == 'Bash'",
      "command": "bash ~/.agents/jev-superpowers/hooks/pre-tool"
    }
  ]
}
Gate 2: Pre-Commit (Diff & Quality Reflex) Pre-Commit

Standard git pre-commit hook wired to git-jev. Evaluates the staged patch for architectural integrity, broken imports, and secret exfiltration before committing to git history.

#!/usr/bin/env bash
# .git/hooks/pre-commit
git-jev check || {
  echo "[BLOCKED] git-jev semantic gate rejected staged changes"
  exit 1
}
Gate 3: Stop Hook (Limpet Completion Policy) Turn Completion

Intercepts the agent's turn completion or exit signal. limpet runs test assertions and compiler diagnostics. If any verification check fails, exit code 1 is returned with failure logs, forcing the agent to stay in context and resolve the issues.

{
  "Stop": [
    {
      "command": "bash ~/.agents/jev-superpowers/hooks/stop"
    }
  ]
}

Integration Matrix

Multi-Harness Hook Configurations

jev-superpowers ships drop-in manifests for all major autonomous coding agent runtimes.

Agent Platform Manifest Location Active Hooks
Claude Code .claude-plugin/plugin.json SessionStart, PreToolUse, Stop
Cursor .cursor-plugin/hooks-cursor.json PreToolUse, PostToolUse, Stop
OpenCode .opencode/plugins/superpowers.js onToolCall, onTurnEnd
Pi Agent .pi/extensions/superpowers.ts tool_call_gate, turn_complete
Codex & Hermes .codex-plugin/plugin.json pre-command, stop-policy
FRAMEWORK ARCHITECT

Akash Priyadarshi

Patna, Bihar, India

Software engineer specializing in AI agent security, sub-second decision oracles, and deterministic developer tooling. Creator of jev-superpowers, jev-seo, jev-curate, and tdlib-android.