Structured Data
Capability Metadata
| Field | Value |
|---|---|
| ID | CAP-098 |
| Version | v1.27 |
| Domain | Specialist Domains |
| Group | Knowledge Packs |
| Status | Documented |
| Related | CAP-001, CAP-099, CAP-104 |
| Default confidence | 0.7 |
| Activation modes | passive, active, interrupt |
Configuration Reference
Hook pattern syntax: regex string or keyword list with confidence threshold
Activation modes:
passive — record observation, do not interrupt session
active — load knowledge pack context into session
interrupt — surface knowledge pack suggestion to user
Hook chaining: compound triggers require multiple patterns to match before activation
interface ObservationHook {
pattern: string | RegExp; // What to match in session content
confidence: number; // Required match confidence (0-1)
mode: 'passive' | 'active' | 'interrupt';
handler: (match: HookMatch) => void;
}
// Example: AGC assembly detection
const agcHook: ObservationHook = {
pattern: /\b(TC|CCS|INDEX|EXTEND|BANK|SETLOC)\b/,
confidence: 0.7,
mode: 'active',
handler: (match) => knowledgePack.recordObservation(match)
};Technical Specifications
Extends: core observation system (CAP-001) with domain-specific pattern matching
Pattern evaluation: hooks evaluated against session content at each tool call boundary
Confidence threshold: 0.7 default — reduces cross-domain false positives (e.g., AGC keywords appearing in Python projects)
Hook declarations: defined in knowledge pack YAML frontmatter (CAP-104 format)
Overview
Observation Hooks bring domain awareness to the core observation system — instead of treating all session content uniformly, knowledge packs teach the observer what domain-specific signals look like. When a session contains AGC assembly syntax, the AGC knowledge pack activates its hooks and begins targeted observation. When Minecraft redstone keywords appear, the Minecraft knowledge pack activates. Each domain gets its own observation lens.
Hooks are declared in the knowledge pack's YAML frontmatter (defined in CAP-104) and evaluated at session content boundaries. A hook matches when the session content contains the hook's pattern at or above the configured confidence threshold. The activation mode determines what happens next: passive hooks record silently, active hooks load domain context, and interrupt hooks surface a suggestion to the user.
The confidence threshold is the key calibration lever. Too low, and AGC assembly keywords in a Python project falsely activate the AGC knowledge pack. Too high, and genuine AGC sessions fail to activate. The 0.7 default was tuned across multiple specialist domains to minimise false positives while maintaining high recall for genuine domain work.
History
The hook system was motivated by false positives in domain-agnostic observation — AGC assembly keywords appearing in a Python project shouldn't activate AGC knowledge packs. The original observation system (CAP-001) treated all session content as equivalent input for pattern detection, which meant domain-specific patterns were indistinguishable from workflow patterns.
Observation Hooks were introduced in v1.26 as a layer between raw session content and the pattern detection pipeline. Rather than modifying the core observer, hooks act as domain-specific filters that pre-classify session content before it enters the pipeline. The hook chaining mechanism (requiring multiple patterns to co-occur) was added specifically to handle ambiguous vocabulary that appears in multiple domains — a term like "address" appears in both AGC assembly and everyday English, but "address AND octal AND register" is unambiguously AGC.
Key Concepts
Imagine you have a friend who's an expert in Apollo spacecraft computers. They're sitting next to you as you work, but they only speak up when you're actually working on Apollo-related stuff — not every time you mention the word "navigation" in a general context.
That selective attention is what Observation Hooks provide. The hook pattern is like teaching your friend which words and phrases are AGC-specific enough to be worth paying attention to. The confidence threshold is like setting how certain they need to be that you're doing AGC work before they speak up — 70% confident means they'll mention it if there are a few AGC keywords, but not for a single ambiguous term.
Usage Examples
Example 1: Declaring hooks in a knowledge pack
# In knowledge pack YAML frontmatter (CAP-104 format)
observation_hooks:
- pattern: "agc|dsky|verb noun|tc |ccs "
confidence: 0.8
mode: active
# Compound trigger: both patterns must appear
- pattern: "octal AND register AND accumulator"
confidence: 0.9
mode: interruptExample 2: Programmatic hook registration
// Hook registered from knowledge pack YAML at load time
observationSystem.registerHook({
packId: 'apollo-agc-basics',
pattern: /\b(TC|CCS|INDEX|EXTEND|BANK|SETLOC)\b/,
confidence: 0.7,
mode: 'active',
handler: (match) => knowledgePack.recordObservation(match)
});