ultimate-pi 0.1.2 → 0.1.3

package/vault/wiki/concepts/Prompt Enhancement.md

@@ -0,0 +1,90 @@
+---
+type: concept
+title: "Prompt Enhancement"
+created: 2026-04-30
+status: developing
+tags:
+  - prompt-engineering
+  - context
+  - retrieval
+aliases:
+  - Prompt Enrichment
+  - Context Injection
+related:
+  - "[[Context Engine (AI Coding)]]"
+  - "[[Semantic Codebase Indexing]]"
+sources:
+  - "[[Augment Code WorkOS ERC 2025]]"
+  - "[[Augment Code Codacy AI Giants]]"
+updated: 2026-05-02
+
+---# Prompt Enhancement
+
+The process of automatically enriching a user's query with relevant codebase context before it reaches the LLM. The goal is to give the LLM the same understanding a senior engineer would have when approaching a task.
+
+## How Augment's Prompt Enhancer Works
+
+1. User types a query: "add logging to payment API."
+2. Context Engine semantically searches the codebase for relevant code.
+3. Enhancer constructs an augmented prompt containing:
+   - The original query.
+   - Relevant source files and their paths.
+   - Existing patterns (how logging is done elsewhere).
+   - Related utilities and libraries already in the codebase.
+   - Team conventions and coding standards.
+4. The augmented prompt is sent to the LLM.
+
+## Key Design Principles
+
+### Reuse Over Reinvention
+The enhancer actively detects existing utilities and libraries. In Augment's demo, when asked to add Git branch info to a status bar, the enhancer detected an existing internal Git library and guided the agent to use it instead of shelling out to git.
+
+### Context Budget Management
+The enhancer must balance context richness with token budget:
+- Retrieve only what's relevant (semantic search).
+- Compress retrieved context (summarize large files).
+- Rank by relevance, not just similarity.
+- Respect the model's context window.
+
+### Pattern Recognition
+The enhancer learns from the codebase:
+- Naming conventions.
+- Error handling patterns.
+- Import structure.
+- Testing patterns.
+- Architectural layering.
+
+## Implementation for Our Harness
+
+```python
+def enhance_prompt(query: str, workspace: str) -> str:
+    # 1. Semantic search for relevant code
+    relevant_files = semantic_search(query, workspace, top_k=10)
+    
+    # 2. Extract patterns from relevant files
+    patterns = extract_patterns(relevant_files)
+    
+    # 3. Find existing utilities/libraries
+    utilities = find_related_utilities(query, workspace)
+    
+    # 4. Fetch wiki knowledge (our existing knowledge base)
+    wiki_context = query_wiki(query)
+    
+    # 5. Build augmented prompt
+    return build_prompt(
+        query=query,
+        relevant_code=relevant_files,
+        patterns=patterns,
+        utilities=utilities,
+        wiki=wiki_context
+    )
+```
+
+## Integration with Existing Harness
+
+Our harness already has several context sources:
+- **lean-ctx**: Exact file retrieval (grep, find, read).
+- **wiki**: Architectural knowledge, research, patterns.
+- **ctx_knowledge**: Persistent project conventions and gotchas.
+
+Prompt enhancement would unify these into a preprocessing step before the main agent loop.

package/vault/wiki/concepts/Prompt Renderer.md

@@ -0,0 +1,89 @@
+---
+type: concept
+title: "Prompt Renderer"
+created: 2026-05-02
+updated: 2026-05-02
+tags:
+  - prompt-renderer
+  - multi-model
+  - build-time-compilation
+  - harness
+status: developing
+related:
+  - "[[provider-native-prompting]]"
+  - "[[model-adaptive-harness]]"
+  - "[[research: Prompt Renderer for Multi-Model Agent Harness]]"
+sources:
+  - "[[Source: Build-Time Prompt Compilation Architecture]]"
+  - "[[Source: AgentBus Jinja2 Prompt Pipelines]]"
+
+---# Prompt Renderer
+
+A build-time prompt compilation system that takes a **base prompt spec** (model-agnostic) and renders **per-model optimized prompts** by applying each model's official prompting conventions, substituting variables, and caching compiled output.
+
+## Architecture
+
+```
+Base Prompt Spec (JSON/YAML)
+        ↓
+  [Compile-time Renderer]
+        ↓
+┌───────┼───────┬─────────┐
+│ GPT   │Claude │Gemini   │  ← Per-model compiled prompts
+│.json  │.json  │.json    │
+└───────┴───────┴─────────┘
+        ↓
+  [npm package]              ← Shipped in lib
+        ↓
+  [Runtime] → load pre-compiled prompt → substitute runtime vars → send to LLM
+```
+
+## Key Properties
+
+- **Build-time, not runtime**: Compiler runs during `npm run build`, output shipped as JSON in npm package
+- **Base spec is model-agnostic**: Single source of truth that describes WHAT the prompt should do, not HOW
+- **Per-model renderers**: Each model gets a plugin that knows its official prompting conventions
+- **Variable system**: Two-phase — compile-time variables (resolved at build) vs runtime variables (resolved at call time)
+- **Caching layer**: Pre-compiled prompts are the cache — no runtime compilation, no warmup needed
+- **Deterministic**: Same spec + same renderer version → identical output (hash-verifiable)
+
+## Rendering Pipeline
+
+1. **Parse base spec**: Validate structure, required fields, variable declarations
+2. **Select model renderer**: Load per-model plugin (GPT, Claude, Gemini, etc.)
+3. **Apply model conventions**: XML tags for Claude, constraints-first for GPT, constraints-last for Gemini
+4. **Substitute compile-time variables**: Resolve all vars marked `compile: true`
+5. **Validate output**: Check token count, syntax, caching thresholds
+6. **Serialize**: Write compiled prompt to JSON with hash + metadata
+7. **Cache**: Store hash → compiled output for incremental builds
+
+## Model-Specific Rendering Rules
+
+| Convention | GPT (OpenAI) | Claude (Anthropic) | Gemini (Google) |
+|-----------|-------------|-------------------|-----------------|
+| System prompt | `system` role message | `system` parameter | `systemInstruction` |
+| Structure | Constraints-first, flat | XML tags, nesting OK | Constraints-last, plain text |
+| Instruction style | Outcome-first, shorter | Long-form, detailed | Multimodal-friendly |
+| Cache control | Auto (no code) | `cache_control: {type: "ephemeral"}` | Explicit context cache |
+| Output format | Function calling | Structured output API | Controlled generation |
+| Best practice source | platform.openai.com/docs/guides/prompt-engineering | docs.anthropic.com + interactive tutorial | cloud.google.com/vertex-ai/docs |
+
+## Variable Substitution
+
+Two-phase variable system:
+
+```yaml
+variables:
+  model_name: { type: string, compile: true }   # Resolved at build
+  user_query: { type: string, compile: false }   # Resolved at runtime
+  max_tokens: { type: number, compile: true, default: 4096 }
+```
+
+Compile-time variables produce multiple compiled variants if multiple values are specified (e.g., `model_name: [gpt-5.2, claude-sonnet-4.5]`).
+
+## Caching Strategy
+
+- **Build cache**: Incremental — only recompile prompts whose spec hash changed
+- **Output cache**: Compiled prompts stored by `{spec_hash}-{model}-{var_hash}.json`
+- **Runtime**: Zero cost — load pre-compiled JSON, substitute runtime vars, send
+- **npm distribution**: Compiled prompts are regular files in the package — no compilation code shipped

package/vault/wiki/concepts/Semantic Codebase Indexing.md

@@ -0,0 +1,67 @@
+---
+type: concept
+title: "Semantic Codebase Indexing"
+created: 2026-04-30
+status: developing
+tags:
+  - code-indexing
+  - embeddings
+  - vector-search
+  - ast
+aliases:
+  - Code Embedding
+related:
+  - "[[Context Engine (AI Coding)]]"
+  - "[[Prompt Enhancement]]"
+sources:
+  - "[[Augment Context Engine Official]]"
+  - "[[Augment Code Codacy AI Giants]]"
+updated: 2026-05-02
+
+---# Semantic Codebase Indexing
+
+The process of converting source code into vector embeddings that capture semantic meaning, enabling similarity search across a codebase without relying on exact keyword matching.
+
+## How It Works
+
+### 1. Code Chunking
+- Split source files into logical units: functions, classes, methods, modules.
+- Use tree-sitter AST parsing for language-aware chunk boundaries.
+- Typical chunk size: 200-500 tokens for optimal embedding quality.
+
+### 2. Embedding Generation
+- Pass each chunk through an embedding model.
+- Options: all-MiniLM-L6-v2 (384-dim, local), CodeBERT, or Voyage AI code embeddings.
+- Augment Code uses custom embedding models trained in pairs for maximum retrieval quality.
+
+### 3. Vector Database Storage
+- Store embeddings in LanceDB, ChromaDB, or Qdrant.
+- Index for fast approximate nearest neighbor (ANN) search.
+- Attach metadata: file path, line range, function/class name, dependencies.
+
+### 4. Real-time Sync
+- Watch filesystem for changes using watchdog/inotify.
+- Re-embed changed files incrementally.
+- Augment claims "millisecond-level sync."
+
+### 5. Hybrid Search
+- Combine vector similarity (semantic) + BM25/ keyword (lexical).
+- Re-rank results by relevance, recency, and relationship proximity.
+
+## Why Semantic > Grep
+
+| Aspect | Grep/Keyword | Semantic Indexing |
+|--------|-------------|-------------------|
+| Finds related code | Only exact matches | Finds semantically similar code |
+| Understands intent | No | Yes — "payment logging" finds telemetry, billing, audit |
+| Cross-language | No | Partially — embeddings capture patterns |
+| Relationship aware | No | Yes — understands call graphs and imports |
+| Noise filtering | Manual | Automatic relevance ranking |
+
+## Implementation Stack (for our harness)
+
+- **Parser**: tree-sitter (18 languages via lean-ctx).
+- **Embeddings**: sentence-transformers (all-MiniLM-L6-v2) or voyage-code-2.
+- **Vector DB**: LanceDB (embedded, zero-config) or ChromaDB.
+- **Sync**: watchdog (Python).
+- **Search**: hybrid BM25 + cosine similarity with re-ranking.

package/vault/wiki/concepts/additive-config-hierarchy.md

@@ -0,0 +1,16 @@
+---
+type: concept
+status: stub
+created: 2026-05-02
+updated: 2026-05-02
+tags: [concept, configuration, claude-code]
+---
+
+# Additive Config Hierarchy
+
+Configuration pattern from Claude Code: config layers stack additively (CLAUDE.md → project-level → user-level → system-level) rather than overriding. Each layer adds context rather than replacing previous layers.
+
+## References
+
+- [[claude-code-architecture-karaxai-2026]]
+- [[harness-configuration-layers]]

package/vault/wiki/concepts/agent-artifacts-verifiable-deliverables.md

@@ -0,0 +1,71 @@
+---
+type: concept
+title: "Agent Artifacts (Trust via Verifiable Deliverables)"
+status: developing
+created: 2026-05-01
+updated: 2026-05-01
+tags:
+  - antigravity
+  - verification
+  - trust
+  - harness-design
+aliases: ["Artifact system", "verifiable artifacts"]
+related:
+  - "[[adversarial-verification]]"
+  - "[[automated-observability]]"
+  - "[[harness-implementation-plan]]"
+  - "[[antigravity-agent-first-architecture]]"
+sources:
+  - "[[google-antigravity-official-blog]]"
+  - "[[cursor-vs-antigravity-2026]]"
+
+---# Agent Artifacts: Trust via Verifiable Deliverables
+
+Google Antigravity's Artifact system replaces raw tool-call logs with human-readable, verifiable deliverables that agents generate as they work.
+
+## What Are Artifacts?
+
+Structured, verifiable outputs agents produce during execution:
+- Task lists and implementation plans
+- Screenshots and browser recordings
+- Walkthrough documents
+- Test result summaries
+- Architecture diagrams
+
+Artifacts represent work at a **task level**, not an API-call level. They are designed to be audited by humans, not parsed by machines.
+
+## How Artifacts Build Trust
+
+```
+Raw tool logs: "execute_command: npm install" → "exit 0" → "write_file: src/auth.ts" → ...
+Artifact: "Authentication migration plan" → "Screenshot: login page working" → "Test results: 23/23 pass"
+```
+
+The second format is reviewable in seconds. The first requires scrolling through hundreds of lines.
+
+## Feedback on Artifacts
+
+- Developers comment on artifacts (Google Docs-style commenting)
+- Agents incorporate feedback **without stopping execution**
+- Feedback is asynchronous: you comment, the agent picks it up at the next checkpoint
+- No need to restart tasks for mid-course corrections
+
+## Comparison with Our Harness
+
+| Dimension | Our Harness (L4 + L5) | Antigravity Artifacts |
+|-----------|----------------------|----------------------|
+| Verification type | Adversarial critic agents | Human-reviewable deliverables |
+| Feedback loop | Multi-round debate (selective) | Async comments on artifacts |
+| Trust mechanism | Critic proves work wrong | Agent proves work right |
+| Cost | LLM tokens (critic rounds) | Human attention (review artifacts) |
+
+## Gap Analysis
+
+Our L4 adversarial verification asks: "Is this correct?" (critic finds flaws).
+Antigravity's Artifacts ask: "Here's proof this is correct" (agent demonstrates success).
+
+These are **complementary**. The critic catches what the agent missed. The artifact proves what the agent got right. Both should exist in the harness.
+
+## Proposed Integration: Phase P31
+
+Add an **Artifact Generation Layer** after L4 verification. Agents generate screenshots, browser recordings, and test result summaries as verifiable proof of work. These artifacts feed into L5 observability and serve as the human-reviewable interface.

package/vault/wiki/concepts/agent-browser-browser-automation.md

@@ -0,0 +1,99 @@
+---
+type: concept
+title: "agent-browser — Rust-Native Browser Automation for AI Agents"
+status: developing
+created: 2026-05-02
+updated: 2026-05-02
+tags:
+  - browser-automation
+  - ai-agents
+  - vercel-labs
+  - rust
+  - cdp
+  - headless-browser
+aliases: ["agent-browser", "Vercel Labs agent-browser"]
+related:
+  - "[[browser-subagent-visual-verification]]"
+  - "[[harness-implementation-plan]]"
+  - "[[Source: Vercel Labs agent-browser]]"
+sources:
+  - "[[Source: Vercel Labs agent-browser]]"
+---
+
+# agent-browser — Rust-Native Browser Automation for AI Agents
+
+Vercel Labs agent-browser (31.4K GitHub stars, Apache 2.0, v0.26.0) is the leading open-source browser automation CLI built specifically for AI agents. Rust-native single binary, 112 contributors, 81 releases, 568 commits.
+
+**Supersedes**: [[browser-harness-agent]] (9.4K stars, MIT, Python) — replaced May 2026 for P30. agent-browser has 3.3× more stars, richer AI agent integration, and Rust-native performance.
+
+## Core Design
+
+Unlike Puppeteer/Playwright (human scripting APIs) and browser-harness (raw CDP with self-healing), agent-browser provides an **agent-native interface**: snapshot-based element refs (`@e1`, `@e2`), JSON output, annotated screenshots, structured diff, and a built-in skills system. The AI agent thinks in terms of refs from snapshots — not CSS selectors, not CDP method calls.
+
+## Key Innovations for AI Agents
+
+### 1. Snapshot + Refs Workflow
+```
+agent-browser snapshot -i --json
+→ Returns: {"refs": {"e1": {"role":"button","name":"Submit"}, "e2": {"role":"textbox","name":"Email"}}}
+agent-browser click @e1          # deterministic, no DOM re-query
+agent-browser fill @e2 "text"    # refs survive page changes until re-snapshot
+```
+
+### 2. Annotated Screenshots
+```
+agent-browser screenshot --annotate
+→ Screenshot with numbered labels [1], [2], [3] matching @e1, @e2, @e3 refs
+→ Multimodal models can reason about visual layout + refs simultaneously
+```
+
+### 3. Structured Diff
+```
+agent-browser diff screenshot --baseline before.png -o diff.png
+agent-browser diff snapshot --baseline before-snapshot.txt
+→ Structural + visual diff for verifying UI changes
+```
+
+### 4. React Introspection
+```
+agent-browser open --enable react-devtools <url>
+agent-browser react tree           # full component tree
+agent-browser react suspense       # suspense boundaries + classifier
+agent-browser vitals               # LCP/CLS/TTFB/FCP/INP + React hydration
+```
+
+### 5. Batch Mode
+```
+agent-browser batch "open url" "snapshot -i" "click @e1" "screenshot"
+→ Multiple commands in single CLI invocation, reduces process startup overhead
+```
+
+### 6. Built-in Skills
+```
+agent-browser skills get core      # 420-line usage guide for agents
+npx skills add vercel-labs/agent-browser  # install skill stub
+```
+
+## Architecture
+
+- **Rust CLI** + **Rust Daemon**: Single binary. Daemon auto-starts, persists between commands
+- **Client-daemon**: Fast subsequent commands (no browser restart)
+- **Direct CDP**: Like browser-harness — raw DevTools Protocol, no Puppeteer wrappers
+- **Multi-provider**: Local Chrome + 6 cloud providers (Browserless, Browserbase, Browser Use, Kernel, AgentCore, iOS)
+
+## Integration with P30
+
+P30 Browser Subagent dispatches via P25 router for UI tasks. Harness invokes `agent-browser` CLI as a subprocess (or via batch mode for multi-step workflows). Config at `.pi/harness/browser.json`.
+
+**What we use**:
+- Snapshot + refs for element interaction
+- Annotated screenshots for visual verification
+- Diff for before/after comparison
+- Batch mode for multi-step agent workflows
+- `--json` for structured output parsing
+
+**What we skip**:
+- Dashboard (CLI harness only)
+- AI Chat (our agent IS the chat)
+- Cloud providers (local Chrome only; opt-in for serverless)
+- iOS Simulator (web-focused; opt-in)

package/vault/wiki/concepts/agent-codebase-interface.md

@@ -0,0 +1,43 @@
+---
+type: concept
+title: "Agent-Codebase Interface (ACI)"
+created: 2026-04-30
+updated: 2026-04-30
+tags:
+  - agent-architecture
+  - codebase-exploration
+  - interface-design
+related:
+  - "[[swe-agent-aci]]"
+  - "[[research-agent-first-codebase-exploration]]"
+status: developing
+
+---# Agent-Codebase Interface (ACI)
+
+The design of tool interfaces specifically for AI agents — not humans — to interact with codebases. Extends the SWE-agent concept of Agent-Computer Interfaces to codebase exploration specifically.
+
+## Core Principle
+
+Agents process information differently from humans. They have:
+- **Fixed context windows** (not infinite working memory)
+- **Token-based costs** (every byte of context has a cost)
+- **No visual cortex** (can't "see" code structure, need explicit representations)
+- **No intuition** (can't form mental models from partial exposure)
+- **Perfect recall within context** (but zero recall outside it)
+
+Therefore, the interface must:
+1. Maximize information density per token
+2. Present structured, machine-parseable representations
+3. Support progressive disclosure (drill down on demand)
+4. Enable autonomous navigation decisions
+
+## Contrast with Human Interfaces
+
+| Human Interface | Agent Interface |
+|----------------|-----------------|
+| Syntax highlighting, file trees | AST symbol maps, dependency graphs |
+| Scroll through files | Fetch specific symbol definitions |
+| Visual pattern recognition | Semantic search + structured queries |
+| Gradual immersion ("Paper Cuts") | Bulk ingestion + ranking algorithms |
+| IDE debugging (step-through) | Execution feedback loops (run tests, check output) |
+| "Use the project" to learn | "Map the project" to learn |

package/vault/wiki/concepts/agent-harness-architecture.md

@@ -0,0 +1,67 @@
+---
+type: concept
+tags:
+  - harness
+  - architecture
+  - context-engineering
+  - safety
+related:
+  - "[[Agentic Orchestration Pipeline]]"
+  - "[[Context Engineering]]"
+  - "[[Safety Defense-in-Depth]]"
+  - "[[sources/martin-fowler-harness-engineering]]"
+  - "[[sources/opendev-arxiv-2603.05344v1]]"
+---
+
+# Agent Harness Architecture
+
+The harness is everything in an AI coding agent except the model itself: the runtime orchestration layer that wraps the reasoning loop and coordinates tool dispatch, context management, safety enforcement, and session persistence. Defined as: **Agent = Model + Harness**.
+
+## Two-Phase Model
+
+### Scaffolding (Pre-Runtime)
+Runs once before the first prompt. Assembles the agent:
+- System prompt compilation (conditional, priority-ordered sections)
+- Tool schema building (from registry, MCP discovery, subagent schemas)
+- Subagent registration and initialization
+
+### Harness (Runtime)
+Operates continuously during execution:
+- Tool dispatch with safety gating
+- Context lifecycle management (compaction, reminders, memory)
+- Approval workflows (Manual/Semi-Auto/Auto)
+- Session persistence and undo tracking
+
+## Feedforward + Feedback Model
+
+| Direction | Type | Examples |
+|-----------|------|----------|
+| **Feedforward (Guides)** | Steer before action | System prompts, AGENTS.md, Skills, coding conventions, architecture docs |
+| **Feedback (Sensors)** | Observe after action | Linters, tests, review agents, type checkers, structural analysis |
+
+Two execution modes:
+- **Computational**: Deterministic, fast — tests, linters, type checkers
+- **Inferential**: LLM-based, semantic — AI code reviews, "LLM as judge"
+
+## The Steering Loop
+
+Human developers iterate on the harness: whenever an issue occurs repeatedly, improve feedforward guides or feedback sensors. Agents can help build harness components (write tests, generate linter rules, create documentation).
+
+## Harness Layers (OpenDev Reference)
+
+1. **Prompt Composition**: Conditional sections sorted by priority, provider-specific variants, ${VAR} substitution, two-part caching
+2. **Context Engineering**: Staged compaction, event-driven reminders, dual-memory architecture, tool result optimization
+3. **Tool System**: Registry with handler categories, lazy MCP discovery, batch execution, 9-pass fuzzy edit matching
+4. **Safety System**: 5-layer defense-in-depth (prompt → schema → approval → validation → hooks)
+5. **Persistence**: Session storage, operation log/undo, configuration hierarchy, provider cache
+
+## Harness Templates
+
+For common topologies (CRUD APIs, event processors, dashboards), a harness template bundles guides + sensors as a reusable package. Teams select tech stacks partly based on available harnesses.
+
+## Relevance to Our Harness
+
+Our current harness architecture:
+- **Scaffolding**: `.pi/skills/` system, agent prompt engineering, wiki as knowledge base
+- **Runtime**: `lean-ctx` for tool routing, `Agent` for subagent spawning, `wiki-autoresearch` for research
+- **Gaps**: No safety defense-in-depth, no staged compaction, no event-driven reminders, no team dispatch, no sequential chaining

package/vault/wiki/concepts/agent-loop-detection-patterns.md

@@ -0,0 +1,133 @@
+---
+aliases: ["agent loop patterns", "stuck agent detection", "tool call loops"]
+type: concept
+title: "Agent Loop Detection Patterns"
+created: 2026-04-30
+status: developing
+tags:
+  - concept
+  - loop-detection
+  - agent-reliability
+  - production
+related:
+  - "[[Research: Meta-Agent Context Drift Detection]]"
+  - "[[context-drift-in-agents]]"
+  - "[[meta-agent-context-pruning]]"
+  - "[[langsight-loop-detection]]"
+  - "[[ironclaw-drift-monitor]]"
+updated: 2026-05-02
+
+---# Agent Loop Detection Patterns
+
+Production-grade detection patterns for identifying when an AI agent is stuck in a non-productive loop. Based on LangSight's production experience and ironclaw's DriftMonitor proposal.
+
+## Three Loop Types
+
+### 1. Direct Repetition
+
+Same tool called with identical arguments multiple times in a row. Most common pattern.
+
+**Cause**: Tool returns error or unexpected result. LLM's retry logic doesn't distinguish "transient failure, retry" from "structural failure, give up."
+
+**Real-world example**: Support agent called `crm-mcp/lookup_customer` 89 times with identical arguments. CRM returned slightly malformed response. Agent decided it needed more data, called same tool, got same malformed response, repeated. Cost: $214.
+
+**Detection**: `SHA256(tool_name + normalized_args)[:16]`. If same hash appears ≥3 times in session window, flag as loop.
+
+### 2. Ping-Pong Between Tools
+
+Two tools called alternately without state change between calls.
+
+**Example**: Agent calls CRM → gets customer → calls Billing → gets invoices → calls CRM again with same args → calls Billing again.
+
+**Detection**: Sequence pattern matching on last 6 calls. A-B-A-B-A-B pattern triggers detection.
+
+### 3. Retry-Without-Progress
+
+Tool call succeeds (no error) but response doesn't satisfy agent's internal goal. Agent keeps calling with minor argument variations.
+
+**Detection**: Semantic similarity of consecutive reasoning outputs >0.95 cosine across multiple steps. Computationally expensive.
+
+## Detection Approaches
+
+### Approach 1: Argument Hash (Recommended)
+
+```python
+import hashlib, json
+from collections import Counter
+
+def compute_call_hash(tool_name: str, args: dict) -> str:
+    payload = f"{tool_name}:{json.dumps(args, sort_keys=True)}"
+    return hashlib.sha256(payload.encode()).hexdigest()[:16]
+
+class LoopDetector:
+    def __init__(self, threshold: int = 3):
+        self.threshold = threshold
+        self.call_counts = Counter()
+
+    def record_call(self, tool_name: str, args: dict) -> bool:
+        call_hash = compute_call_hash(tool_name, args)
+        self.call_counts[call_hash] += 1
+        return self.call_counts[call_hash] >= self.threshold
+```
+
+Catches >90% of real-world loops with zero false positives at threshold 3.
+
+### Approach 2: Sliding Window Rate
+
+Count tool calls regardless of argument variation. If tool called >N times in M seconds, flag.
+
+```python
+from collections import deque
+from datetime import datetime, timedelta
+
+class RateLoopDetector:
+    def __init__(self, max_calls: int = 10, window_seconds: int = 60):
+        self.max_calls = max_calls
+        self.window = timedelta(seconds=window_seconds)
+        self.call_times: dict[str, deque] = {}
+
+    def record_call(self, tool_name: str) -> bool:
+        now = datetime.utcnow()
+        if tool_name not in self.call_times:
+            self.call_times[tool_name] = deque()
+        times = self.call_times[tool_name]
+        while times and now - times[0] > self.window:
+            times.popleft()
+        times.append(now)
+        return len(times) >= self.max_calls
+```
+
+### Approach 3: LLM Similarity
+
+Compare semantic similarity between consecutive reasoning outputs. Most sophisticated but computationally expensive. Usually overkill — Approaches 1+2 catch >90%.
+
+## Intervention Strategies
+
+| Strategy | When | Risk |
+|----------|------|------|
+| **Warn + continue** | Early monitoring, unsure about thresholds | No false-termination risk, but loops continue |
+| **Terminate session** | Production, confident in thresholds | False termination loses partial work |
+| **Inject recovery** | Want agent to self-correct | Agent may ignore or loop again |
+| **Prune + restart** | Proposed meta-agent pattern | Pruning may remove useful context |
+
+## Threshold Tuning
+
+- **Default**: 3 identical calls. Works for most agents.
+- **Polling agents**: Use time-based windows (Approach 2), not count-based.
+- **Retry-heavy workflows**: Increase to 5-7.
+- **Sub-agents**: Each sub-agent gets own detector. Parent calling same sub-agent multiple times is not a loop.
+- **Start with warn, switch to terminate**: Monitor for a week, then enforce.
+
+## Always Combine With Budget Guardrails
+
+Loop detection catches known patterns. Budget guardrails catch unknown patterns:
+- Max cost per session ($1 default)
+- Max steps (25 default)
+- Max wall time (120s default)
+- Soft alert at 80% of budget
+
+## See Also
+
+- [[meta-agent-context-pruning]] — Extends detection with pruning + restart
+- [[langsight-loop-detection]] — Source: production deployment guide
+- [[ironclaw-drift-monitor]] — Source: 5-rule DriftMonitor proposal