State Hook Management
Relevant source files
The following files were used as context for generating this wiki page:
State Hook Management manages the lifecycle of agent events by capturing, processing, and storing interactions between developers and coding agents. The system wires itself into third-party agents, receives event payloads via standard input, and maintains a sequence of records that form the project's memory.
This module provides the mechanism to track session state, handle repository-specific context, and manage the transition of raw captured data into curated knowledge. It supports multiple agents including Claude, Codex, Grok, and Cursor by implementing specific hook handlers for each.
Sources: src/main.rs:1-30, src/setup.rs:15-30, src/capture.rs:1-10
Architecture and Event Flow
The hook management system operates as a fail-open gateway. When an agent triggers a hook, the oboete hook command receives a JSON payload. The system extracts session metadata, redacts sensitive information based on defined rules, and appends the event to a persistent store.
Hook Execution Lifecycle
The diagram shows the synchronous path from an agent event to persistent storage.
Sources: src/main.rs:188-195, src/capture.rs:88-120, src/setup.rs:140-155
Key Functions and Structures
| Component | Description |
|---|---|
HookCommand | Generates the command string for agent configuration files. |
capture::events | Transforms a JSON hook payload into one or more Captured events. |
Settings | Holds user preferences for prompt storage and redaction rules. |
Gate | Scans and redacts strings before they reach the database. |
Sources: src/setup.rs:114-135, src/capture.rs:43-65, src/capture.rs:184-210
Agent Integration and Setup
Oboete integrates with various coding agents by modifying their configuration files to include command-line hooks. The oboete setup command automates this wiring process.
Supported Agents and Events
The system tracks specific events depending on the agent's capabilities. Common events include:
SessionStart: Initializes tracking for a new agent interaction.UserPromptSubmit: Captures the developer's instructions.PostToolUse: Records the output and status of agent-executed tools.Stop: Captures the final assistant response.SessionEnd: Finalizes the session record.
Sources: src/setup.rs:19-55, src/capture.rs:95-150
Configuration Management
The setup module performs atomic writes to agent configuration files (like settings.json for Claude or config.toml for Codex) to ensure reliability. It creates backups with a .oboete.bak suffix before making changes.
The sequence diagram illustrates the safe configuration update process.
Sources: src/setup.rs:242-260, src/setup.rs:324-350
Redaction and Security Gates
A critical part of hook management is the "Egress Gate," which prevents secrets from being stored or displayed. The system applies redaction during capture and again during retrieval.
Capture-time Redaction
The Gate structure in capture.rs scans every stored string. If a string exceeds MAX_FIELD_BYTES (64 KB), the system keeps only the head and tail, inserting a marker indicating the full size. Binary content (like images) is replaced with a metadata marker containing the MIME type and a SHA256 hash.
Sources: src/capture.rs:19-25, src/capture.rs:184-230, src/capture.rs:315-330
State Tracking (hookstate.rs)
The system maintains transient state for active sessions to handle context injection and turn counting.
- It tracks the current repository and branch using Git file analysis.
- it counts turns within a session to detect gaps between captured records and agent transcripts.
Sources: src/hookstate.rs:1-50, src/capture.rs:335-360
Curated Window Management
Captured events are organized into "Windows" for curation. A window is a sequence of records from a single device, capped by token count or record count.
| Constant | Value | Description |
|---|---|---|
WINDOW_TOKENS | 5,000 | Target size for a curator LLM prompt. |
MAX_RECORDS | 2,000 | Maximum number of records a single window can cover. |
TOOL_INPUT_CHARS | 2,000 | Maximum input text shown for tool calls in a window. |
Sources: src/curate.rs:19-35
Window Splitting Logic
If an event is too large for the remaining budget in a window, the system splits it. The Piece structure tracks byte offsets (from_offset, to_offset) within a single record to ensure the next window starts exactly where the previous one ended.
Sources: src/curate.rs:175-230, src/curate.rs:370-400
Summary
State Hook Management provides the foundational layer for Oboete's memory. It handles the transition from volatile agent events to structured, redacted records in raw.db. By automating agent configuration and implementing robust redaction gates, it ensures that developer interactions are recorded reliably and securely across diverse coding environments.
Sources: src/main.rs:1-30, src/capture.rs:1-20