lucifer-gate

Intercepts outbound commands from AI agents before execution by acting as a proxy layer in the command pipeline. Routes all agent-initiated actions through a centralized gate that evaluates whether to forward, block, or escalate based on configured policies. Implements a middleware pattern that sits between the agent's decision layer and actual system command execution, enabling transparent inspection without modifying agent code.

Sends pending command requests to a Telegram bot interface where authorized users can review, approve, or reject actions in real-time. Implements a request-response pattern using Telegram's message API to deliver command details and capture human decisions, with state management to track approval status across async message exchanges. Supports multiple approvers and maintains audit trails of all approval decisions with timestamps and user identifiers.

Evaluates incoming commands against a set of configured rules or patterns to determine if they should be auto-approved, auto-blocked, or escalated for human review. Uses pattern matching (regex, string matching, or rule-based logic) to classify commands by risk level or category. Supports both allowlist (only execute matching patterns) and blocklist (reject matching patterns) strategies, enabling fine-grained control over which agent actions are permitted without human intervention.

Records all command execution events (attempted, approved, rejected, executed) with full context including command text, approver identity, timestamps, and execution results. Implements structured logging that captures both the decision path (was it auto-approved, escalated, or manually approved?) and the outcome (success/failure/error). Logs are persisted to a durable store and can be queried for compliance auditing, incident investigation, or behavioral analysis of agent actions.

Manages the lifecycle of pending approval requests with configurable timeout windows and fallback behaviors when human approval is not received within a deadline. Implements state machines to track whether a command is waiting for approval, approved, rejected, or timed out. Supports fallback strategies such as auto-reject on timeout, retry with escalation, or queue for later execution, enabling graceful degradation when approvers are unavailable.

Routes approval requests to multiple designated approvers and implements consensus logic (e.g., require 2-of-3 approvals, any single approval, or unanimous approval) to determine final approval status. Tracks which approvers have responded and their decisions, and can escalate to backup approvers if primary approvers don't respond. Supports role-based routing where different command categories are sent to different approver groups based on their expertise or authority level.

Augments command execution requests with contextual metadata to help approvers make informed decisions. Enriches commands with information such as agent identity, execution context, risk assessment, command history, and related system state. Presents this enriched context to approvers via Telegram messages, enabling them to understand not just what command is being executed, but why the agent is executing it and what the potential impact might be.

Captures the outcome of executed commands (success, failure, error messages, side effects) and feeds this information back to approvers and the agent. Implements a feedback loop where approvers can see whether their approval decisions resulted in successful execution or failures, enabling them to refine their approval criteria over time. Provides agents with execution results to inform subsequent decision-making and error recovery.