Documentation
¶
Overview ¶
Package hooksbridge translates a Claude Code (or compatible) harness hook log into AgentProvenance's graph: agent nodes, delegation spawn edges, peer (peer) message edges carrying the message body as objectified evidence, and a tool_call per agent tool invocation bound to the acting agent_id. Each proposed tool call is pre-flighted through the trusted policy engine so an obviously unsafe proposal (e.g. an SSRF to the metadata IP, or a credential read) lands as a status=denied "refused" node -- the app-side half of the blame chain the kernel sensor later confirms.
Trust boundary: everything the bridge writes is APP-ASSERTED context derived from the harness's own hooks (binding_source=hooks). It records no system events and forges no signatures; the deny verdict on a refused node is computed by the trusted engine, not by the model. The kernel sensor remains the ground truth that a syscall actually happened; the bridge only says which agent intended it.
Index ¶
- Constants
- func AdaptHarness(harness string, r io.Reader) (io.Reader, error)
- func AdaptKimiSession(sessionDir string) (io.Reader, error)
- func BridgeTranscript(harness, path string) (io.Reader, error)
- func CorrelateSyscalls(db *sql.DB, runID string) (int, error)
- func HarvestContextIntent(ctx context.Context, db *sql.DB, paths store.Paths, runID string) (int, error)
- type CorrelationReport
- type Options
- type Summary
Constants ¶
const ( EdgeAgentSpawn = "agent_spawn" // delegation: parent/main -> sub-agent (delegation) EdgeAgentMessage = "agent_message" // peer: sender -> body-object -> recipient (peer influence) EdgeAgentToolCall = "agent_tool_call" // agent -> the tool_call it invoked EdgeAgentSyscall = "agent_syscall" // tool_call -> runtime event (inferred command/time/process association) )
Edge types the bridge emits (all app-asserted orchestration structure).
const ( CorrelationMethod = correlation.AppProcessMethod CorrelationConfidence = correlation.AppProcessConfidence )
Variables ¶
This section is empty.
Functions ¶
func AdaptHarness ¶ added in v0.7.1
AdaptHarness wraps a harness-specific session transcript in a reader of the normalized hook-JSONL events Ingest consumes, so a non-Claude-Code harness is captured by translating its OWN session record — no per-harness bespoke bridge. harness "" / "claude" is a passthrough (the events are already normalized).
func AdaptKimiSession ¶ added in v0.7.1
AdaptKimiSession walks a Kimi session directory (…/session_<id>/) and its per-agent wire.jsonl files into one normalized hook stream. The main agent's `Agent` tool call is the delegation dispatch (Kimi reuses Claude Code's tool name), and each agents/<sub>/ becomes a SubagentStart + its own tool calls — so the existing bridge draws the same delegation graph as Claude Code.
func BridgeTranscript ¶ added in v0.7.2
BridgeTranscript opens a harness's session record at path (a Kimi session DIRECTORY, else a transcript file) and returns a reader of normalized hook events ready for Ingest. It is the one entry point launch and `hooks bridge` share, so both handle Kimi's per-agent directory the same way.
func CorrelateSyscalls ¶
CorrelateSyscalls retains the existing entry point. The detailed variant exposes ambiguity and coverage without converting either into a guessed edge.
Types ¶
type CorrelationReport ¶ added in v0.9.0
type CorrelationReport struct {
SchemaVersion string `json:"schema_version"`
RunID string `json:"run_id"`
Method string `json:"method"`
Confidence float64 `json:"confidence"`
Status string `json:"status"`
InputComplete bool `json:"input_complete"`
ObservedAt string `json:"observed_at"`
Ref string `json:"ref,omitempty"`
ToolCalls int `json:"tool_calls"`
UnclockedCalls int `json:"unclocked_calls"`
RuntimeEvents int `json:"runtime_events"`
ExecEvents int `json:"exec_events"`
MatchedExecs int `json:"matched_execs"`
InheritedExecs int `json:"inherited_execs"`
AmbiguousExecs int `json:"ambiguous_execs"`
UnknownScopeEvents int `json:"unknown_scope_events"`
InvalidEvents int `json:"invalid_events"`
Edges int `json:"edges"`
Issues []string `json:"issues,omitempty"`
}
func CorrelateSyscallsTx ¶ added in v0.10.0
func CorrelateSyscallsTx(tx *sql.Tx, runID string) (CorrelationReport, error)
CorrelateSyscallsTx rebuilds attribution inside a caller-owned transaction. The caller must commit the complete analysis or roll back on any error.
func CorrelateSyscallsWithReport ¶ added in v0.9.0
func CorrelateSyscallsWithReport(db *sql.DB, runID string) (CorrelationReport, error)
CorrelateSyscallsWithReport rebuilds only agent_syscall edges in one database snapshot/transaction. Scope association is already recorded by ingestion; this pass adds a weaker app-to-process inference, never kernel-certified intent.
type Options ¶
type Options struct {
RunID string
// PostHoc records observed source outcomes without claiming that a policy
// evaluated after execution actually blocked the tool.
PostHoc bool
// Engine pre-flights each proposed tool call. Zero value -> DefaultEngine.
Engine security.Engine
// Objects stores message bodies as content-addressed evidence objects.
Objects provenance.ObjectStore
// Base is the fallback clock: events without a stamped `ts` are ordered
// monotonically from Base (hook stdin carries no timestamp). Zero -> a fixed
// epoch so synthetic runs are deterministic.
Base time.Time
}
Options configures an ingest.
type Summary ¶
type Summary struct {
Agents int `json:"agents"`
ToolCalls int `json:"tool_calls"`
Refused int `json:"refused"`
SpawnEdges int `json:"spawn_edges"`
MessageEdges int `json:"message_edges"`
Lines int `json:"lines"`
}
Summary reports what an ingest wrote.
func Ingest ¶
Ingest reads a hook JSONL stream and writes the orchestration graph for RunID. Prior bridge-written rows are replaced atomically after the source has been read. It never touches record/sensor rows.
func IngestContext ¶ added in v0.9.0
func IngestContext(ctx context.Context, db *sql.DB, paths store.Paths, runID string) (Summary, error)
IngestContext projects stored, redacted source records into the existing orchestration model. It never opens a current transcript or invents a child identity from a spawn call ID. The original context objects remain immutable.
Source Files