looplet 0.1.7__tar.gz

looplet-0.1.7/.gitignore

@@ -0,0 +1,63 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtualenvs
+.env
+.venv/
+venv/
+ENV/
+
+# PyPA / tooling
+.tox/
+.coverage
+.coverage.*
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+htmlcov/
+coverage.xml
+*.cover
+
+# uv
+uv.lock.backup
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs and local artifacts
+*.log
+logs/
+scratch/
+
+# Type checkers
+.pyre/
+.pytype/

looplet-0.1.7/CHANGELOG.md

@@ -0,0 +1,352 @@
+# Changelog
+
+All notable changes to `looplet` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.7] - 2026-04-21
+
+### Changed (project rename)
+- **Renamed from `openharness` to `looplet`.** The PyPI name
+  `openharness` was taken by an unrelated project, so we renamed
+  before the first public release. The public API (imports, symbol
+  names, protocols) is unchanged except for the top-level package
+  name — update imports from `openharness` to `looplet`. The GitHub
+  repository is also renamed; old URLs redirect automatically.
+
+### Added (launch polish)
+- `ROADMAP.md` with a frozen v1.0 API contract and explicit
+  out-of-scope list.
+- `docs/` site scaffold (tutorial, evals, recipes, hooks, good-first-issues,
+  discussions-seed, demo-script) + mkdocs-material config + GitHub
+  Pages workflow.
+- `THIRD_PARTY_USERS.md` social-proof seed.
+- `src/looplet/examples/ollama_hello.py` — zero-API-key onboarding.
+- Codecov upload step in CI (non-blocking).
+- Leaner README (<170 lines) with the pydantic-ai-harness disambiguation
+  moved to the top.
+
+### Added (evals — pytest-style agent evaluation)
+- **Eval framework** (`looplet.evals`). Write `eval_*` functions
+  that take `EvalContext` and return any of `float`, `bool`, `str`,
+  `dict`, or `EvalResult`. The framework normalizes all return types.
+- **`eval_discover(path)`** — auto-discovers eval functions in
+  `eval_*.py` files (like pytest discovers `test_*`).
+- **`eval_run(evals, ctx)`** — runs evaluators, auto-detects
+  `llm` parameter for LLM-as-judge, catches errors gracefully.
+- **`eval_run_batch(evals, contexts)`** — runs same evals across
+  multiple trajectories with per-eval avg/min/max aggregation.
+- **`eval_mark(*tags)`** — decorator for categorizing evals.
+  `eval_run` and `eval_run_batch` accept `include=`/`exclude=` to
+  filter by marks.
+- **`eval_cli(args)`** — CLI runner with threshold-based pass/fail
+  exit codes for CI integration.
+- **`EvalHook`** — LoopHook that builds EvalContext at `on_loop_end`
+  and runs all evaluators automatically during development.
+- **`EvalContext.from_trajectory_dir()`** — loads context from saved
+  trajectories with support for both looplet and benchmark formats.
+
+### Added (MCP + skills)
+- **`MCPToolAdapter`** — wraps MCP server tools as `ToolSpec` instances
+  via JSON-RPC over stdio. No MCP SDK required.
+- **`Skill`** — bundles tools + context + prompt fragment into one
+  loadable unit. `skill.register(registry)` adds all tools.
+
+### Added (approval)
+- **`ApprovalHook`** — stops the loop when a tool returns
+  `needs_approval=True`. Combined with `checkpoint_dir` for
+  crash-safe async human-in-the-loop approval.
+- Renamed `elicit` → `approval` uniformly: `LoopConfig.approval_handler`,
+  `ToolContext.request_approval`, `ToolContext.approve()`.
+
+### Changed (naming cleanup)
+- Renamed internal names for clarity: `coerce_text` → `to_text`,
+  `DiminishingReturnsTracker` → `StallDetector`,
+  `reactive_compact` → `emergency_truncate`,
+  `compress_session_log` → `age_session_entries`,
+  `enforce_result_budget` → `trim_results`,
+  `should_compress_context` → `is_context_oversized`,
+  `HEAVY_BLOCK_KINDS` → `LARGE_CONTENT_TYPES`,
+  `DefaultSummarizer` → `default_summarizer`.
+- Renamed compact services: `DefaultCompactService` → `TruncateCompact`,
+  `LLMCompactService` → `SummarizeCompact`.
+- Renamed `normalise_hook_return` → `normalize_hook_return`.
+- Moved `concurrent_dispatch` and `reactive_recovery` from `FLAGS`
+  global singleton to `LoopConfig` fields.
+- Trimmed `__all__` from 154 → 54 symbols organized into labeled tiers.
+
+### Changed (developer experience)
+- Added `preview_prompt()` — shows what the LLM sees before the first
+  call. Invaluable for debugging.
+- Added `TrajectoryRecorder.summary()` — one-liner run summary.
+- Added `--trace DIR` to coding_agent example for trajectory recording.
+- Added step-by-step tutorial to README (5 progressive steps).
+- Added `LoopConfig` docstring with "start here" guide listing the
+  4 essential fields.
+- Added `FileCheckpointStore.load_latest()` + auto-resume wiring in
+  `composable_loop` — crash-resume is now one line:
+  `LoopConfig(checkpoint_dir="./ckpt")`.
+
+### Removed
+- Removed `async_loop.py` (feature-frozen, no consumers).
+- Removed 3 mock examples (calculator, code_review, research).
+  Replaced with `hello_world.py` (real LLM) + `coding_agent.py`
+  (Claude Code-equivalent tools: bash, read, write, edit, glob,
+  grep, think, done).
+- Removed all back-compat aliases.
+- Removed all internal project references (cadence, primal_security).
+
+### Added (compaction strategies)
+- **`PruneToolResults`** — new zero-LLM-call compaction service that
+  clears old tool-result content while keeping conversation structure
+  intact. Configurable `keep_recent` (how many recent tool results
+  to preserve) and `compactable_tools` (restrict to specific tools).
+  Cheapest possible compaction — use as the first stage in a chain.
+- **`compact_chain(*services)`** — combinator that tries compaction
+  services in order; first stage that has an effect wins. Replaces
+  the need for a separate `ChainedCompactService` class. Usage:
+  `compact_chain(PruneToolResults(), SummarizeCompact(), TruncateCompact())`.
+- **`CompactOutcome.cleanup`** — optional post-compact callback.
+  When set, `run_compact()` invokes it after firing `POST_COMPACT`.
+  Use for domain-specific state resets (clear caches, re-inject
+  context, reset token baselines) without the loop knowing details.
+
+### Changed (renames — back-compat aliases kept)
+- **`DefaultCompactService`** → **`TruncateCompact`** — clearer name
+  for "drop old entries, keep N recent, zero LLM calls."
+- **`LLMCompactService`** → **`SummarizeCompact`** — clearer name
+  for "LLM summarizes middle, keeps N recent."
+- Old names (`DefaultCompactService`, `LLMCompactService`) remain
+  as aliases and continue to work.
+
+### Added (context management pt. 2)
+- **Prompt caching infrastructure** (`looplet.cache`). New
+  `CachePolicy` dataclass declares which stable prompt sections
+  (system prompt, tool schemas, memory) should carry Anthropic-style
+  `cache_control` markers, with per-section TTL (`ephemeral` / `1h`).
+  `LoopConfig.cache_policy` threads per-turn `CacheBreakpoint` lists
+  (label + SHA-256 hash + TTL) to backends that expose
+  `generate_with_cache(..., cache_breakpoints=[...])`. Backends
+  without the kwarg keep working unchanged — caching is strictly
+  additive. `CacheBreakDetector` ships as a drop-in observer hook
+  that records section-hash changes across turns for cache-miss
+  telemetry.
+- **`LLMCompactService`** — new compaction strategy that spends one
+  LLM call to summarise the session. Produces a dense 4-section
+  summary (task goal, findings, open questions, recent decisions)
+  spliced into the session log as a synthetic entry after
+  keep-recent pruning. Falls back to deterministic keep-recent on
+  any summariser error. Trade-off vs `DefaultCompactService`: one
+  LLM call per compaction for preserved reasoning chains.
+- **Threshold-tier context budgeting** (`looplet.budget`). New
+  `ContextBudget` dataclass with `warning_at` / `error_at` /
+  `compact_buffer` tiers. `ThresholdCompactHook` is a ready-to-register
+  `should_compact` implementation that fires proactive compaction
+  once estimated tokens cross the configured tier.
+  `BudgetTelemetry` observer records per-step tier samples and
+  exposes `peak_tier` for production dashboards.
+
+### Added (architecture improvements)
+- **Proactive compact hook slot** — `LoopHook.should_compact(state,
+  session_log, conversation, step_num) -> bool`. Fires at the top of
+  each step, before prompt build. Any hook returning `True` triggers
+  the configured `CompactService` preemptively. Complements the
+  reactive `prompt_too_long` path — use for message-count or
+  token-estimate heuristics. `StreamingHook` gets a no-op stub.
+- **Tool-result streaming via `TOOL_PROGRESS`** — new
+  `LifecycleEvent.TOOL_PROGRESS`. When hooks are present, the loop
+  builds a `ToolContext.on_progress` callback per tool-call that
+  emits `TOOL_PROGRESS` (with the originating `tool_call`) whenever
+  the tool invokes `ctx.report_progress(stage, data)`. Observers can
+  stream intermediate output from long-running tools without
+  blocking dispatch.
+- **Budget-aware turn continuation** — new
+  `LoopConfig.max_turn_continuations: int = 0`. When `> 0` and the
+  backend exposes `last_stop_reason`, `llm_call_with_retry` will
+  re-prompt up to N times on `stop_reason == "max_tokens"` and
+  concatenate outputs so long thoughts aren't truncated mid-message.
+  `LLMResult` gains `stop_reason` and `continuations` fields.
+- **`build_briefing` / `build_prompt` as hook slots** — both are now
+  optional methods on `LoopHook`. First hook returning a non-`None`
+  string wins; the loop falls back to `LoopConfig.build_briefing` /
+  `config.build_prompt` / the built-in default. Lets domain hooks
+  own prompt construction without threading callables through
+  `LoopConfig` separately.
+- **`DomainAdapter`** — new dataclass bundling the five domain
+  callables (`build_briefing`, `extract_entities`, `build_trace`,
+  `build_prompt`, `extract_step_metadata`) into a single object.
+  `LoopConfig.domain: DomainAdapter | None = None` seeds matching
+  flat fields when they are `None`. Flat fields still win over the
+  adapter, which wins over built-in defaults — use the adapter to
+  package a reusable agent in one handle instead of five kwargs.
+
+### Removed (breaking)
+- **`InvestigationLog`** backward-compat alias is gone — use
+  `SessionLog` directly.
+- **`HARNESS_FLAGS`** backward-compat alias is gone — use `FLAGS`.
+- **Legacy `CADENCE_*` environment variables** for feature flags are
+  no longer read; use the `LOOPLET_*` prefix.
+- **`_clone_tools_excluding`** private alias is gone — use
+  `clone_tools_excluding`.
+- **`LoopConfig.permissions`** is gone. Register a
+  `PermissionHook(PermissionEngine(...))` in `hooks=[...]` instead —
+  it flows through the same unified `HookDecision` + event bus as
+  every other hook.
+
+### Added
+- **Unified hook vocabulary — `HookDecision`** (`looplet.hook_decision`).
+  All hook slots now accept a single `HookDecision` return type (legacy
+  `None` / `bool` / `str` returns still work via `normalise_hook_return`).
+  Helpers `Allow()`, `Deny(reason)`, `Block(reason)`, `Stop(reason)`,
+  `Continue()`, `InjectContext(text)` make intent explicit at the call
+  site.
+- **Lifecycle events — `on_event(payload)`** (`looplet.events`).
+  `LoopHook` gained an optional `on_event(EventPayload)` method. The
+  loop now fires 10 named events: `SESSION_START`, `PRE_LLM_CALL`,
+  `POST_LLM_RESPONSE`, `PRE_TOOL_USE`, `POST_TOOL_USE`,
+  `POST_TOOL_FAILURE`, `PRE_COMPACT`, `POST_COMPACT`, `STOP`,
+  `SUBAGENT_START`, `SUBAGENT_STOP`. Any hook can subscribe with a
+  single method instead of implementing every slot.
+- **`PermissionHook`** (`looplet.permissions`) — wraps
+  `PermissionEngine` and plugs it into the event bus so policy
+  decisions flow through the same `HookDecision` path as custom hooks.
+- **`CompactService` + `DefaultCompactService` + `run_compact(...)`**
+  (`looplet.compact`) — reactive compaction is now a swappable
+  service with `PRE_COMPACT` / `POST_COMPACT` events.
+- **`LoopConfig.render_messages_override`** — byte-exact escape hatch.
+  Receives `(messages, default_prompt, step_num)` and returns the
+  exact prompt string sent to the LLM. Lets advanced callers take full
+  control of prompt rendering without forking the loop.
+- **First-class subagents** — `run_sub_loop(..., subagent_id=...)`
+  now fires `SUBAGENT_START` / `SUBAGENT_STOP` events on the parent's
+  hooks and returns `subagent_id` in the result dict for correlation.
+- **`replay_loop(trace_dir, tools=...)`** — rerun a captured trace
+  through a fresh `composable_loop` without calling the LLM again.
+  Useful for golden-trajectory regression tests, hook A/Bs, and
+  cost-free loop diffs. Raises `RuntimeError` if the replay loop
+  requests more calls than were recorded or diverges in method
+  (`generate` vs `generate_with_tools`). Falls back to
+  `call_NN_response.txt` files when `manifest.jsonl` is missing.
+- **`python -m looplet show <trace-dir>`** — stdlib-only CLI that
+  prints a one-page summary of a captured trace (run id, termination,
+  per-step tool calls with durations, LLM totals). Exit code 1 when
+  the directory is missing or malformed.
+- **`looplet.provenance`** — new module for debugging agent runs:
+  - `RecordingLLMBackend` / `AsyncRecordingLLMBackend` wrap any backend
+    and capture every prompt, system prompt, tool schema, response,
+    duration, and error as `LLMCall` records. `generate_with_tools` is
+    surfaced only when the wrapped backend supports it, so
+    `NativeToolBackend` detection stays honest.
+  - `TrajectoryRecorder` hook captures a structured `Trajectory` per
+    run (steps, context-before, termination reason, embedded `Tracer`
+    spans) and writes `trajectory.json` + `steps/step_NN.json`.
+  - `ProvenanceSink` is a 3-line facade: `wrap_llm(...)`,
+    `trajectory_hook()`, `flush()`.
+  - On-disk layout is diff-friendly: `call_NN_prompt.txt` /
+    `call_NN_response.txt` per LLM call plus a `manifest.jsonl`.
+  - Both recorders accept `redact=` for secret scrubbing and
+    `max_chars_per_call=` for bounded memory.
+  - See [PROVENANCE_GUIDE.md](PROVENANCE_GUIDE.md) for API reference,
+    recipes, and performance notes.
+- `Step.pretty()` — human-readable CLI formatter complementing
+  `Step.summary()` (which is tuned for LLM context assembly).
+
+## [0.1.6] - 2026-04-17
+
+### Added
+- **`looplet.testing`** — public test-utility module exposing
+  `MockLLMBackend` and `AsyncMockLLMBackend` (scripted, zero-dependency)
+  so downstream packages can unit-test hooks, tools, and backends
+  without a real LLM provider.
+- **PyPI publish workflow** (`.github/workflows/publish.yml`) that
+  builds + publishes on version tags via PyPI trusted publishing.
+- **README positioning matrix** comparing `looplet` to LangGraph,
+  DSPy, and smolagents; observability/OTel wiring example; stability &
+  versioning policy; real `AnthropicBackend` usage in quick-start.
+
+### Fixed
+- `resume_loop_state()` now restores the checkpointed `Conversation`
+  thread (was silently dropping multi-turn message history on resume).
+- `RoutingLLMBackend.generate_with_tools` is now gated dynamically via
+  `__getattr__` so `hasattr(llm, "generate_with_tools")` returns a
+  truthful answer for the currently-selected backend (consistent with
+  `_FallbackLLM` and `CostTracker`).
+- Async `__llm_error__` step is now recorded through `_history` to
+  match the sync loop (previously caused session-log/conversation
+  drift on LLM failure).
+
+### Previously added in this release
+- **`ToolError` taxonomy** — structured `ErrorKind` enum
+  (`PERMISSION_DENIED`, `TIMEOUT`, `VALIDATION`, `EXECUTION`, `PARSE`,
+  `CONTEXT_OVERFLOW`, `RATE_LIMIT`, `NETWORK`, `CANCELLED`) plus a
+  `ToolError` dataclass. `ToolResult` now carries both `error: str`
+  (for JSON-safe display) and `error_detail: ToolError` (for
+  introspection).
+- **`PermissionEngine`** — declarative `ALLOW` / `DENY` / `ASK` /
+  `DEFAULT` rules with fail-closed `arg_matcher`, plug-in `ask_handler`
+  for human-in-the-loop, and an append-only denial audit log.
+- **`CancelToken`** — cooperative cancellation is now threaded through
+  `LoopConfig` → `llm_call_with_retry` / `async_llm_call_with_retry`
+  → `ToolContext.cancel_token`, so both the next LLM call and any
+  in-flight tool can stop cleanly.
+- **`ToolContext.elicit`** — `LoopConfig.elicit_handler` surfaces a
+  generic `elicit(prompt) → str` protocol to tools for interactive
+  prompts.
+- **Multi-block messages** — `Message.content` supports a `list` of
+  `ContentBlock(kind, data)` alongside plain `str`. `HEAVY_BLOCK_KINDS`
+  (`image` / `audio` / `video` / `binary`) are stripped before
+  summarization.
+- **Async `build_trace`** — `async_composable_loop` now stashes the
+  built trace on `state.trace` at exit (async generators can't
+  `return` a value).
+- **`SyncToAsyncAdapter.generate_with_tools`** — router-selected sync
+  backends keep native-tools support in the async loop.
+- **Preflight context check** — async loop matches sync by skipping a
+  doomed LLM call when the prompt is already too long under
+  `FLAGS.reactive_recovery`.
+- **Checkpoint state counters** — `resume_loop_state` now round-trips
+  `state.queries_used` and `state.budget_remaining` so budget
+  enforcement continues across resume.
+
+### Changed
+- `ToolResult.error` narrowed back to `str | None` (JSON-safe). Use
+  `ToolResult.error_detail` for structured introspection.
+- `PermissionRule.matches()` now fails closed *per decision type*:
+  `DENY` rules match on matcher errors (block), `ALLOW` / `ASK` rules
+  do not (don't accidentally grant).
+- `PermissionEngine._resolve_default` collapses ambiguous engine
+  defaults (`ASK` / `DEFAULT`) to `DENY` so a decision never leaks into
+  a `PermissionOutcome` where both `.allowed` and `.denied` are False.
+- `ToolSpec._accepts_ctx` is computed eagerly at `register()` time (and
+  self-heals in `dispatch()` for specs inserted directly).
+- `_backend_accepts_cancel_token` cache keyed by `(type, method_name)`
+  instead of `id()` (eliminates id-recycling hazard).
+- `_classify_exception` broadened to detect `asyncio.CancelledError`,
+  rate-limit, context-overflow, and parse exceptions by class name /
+  message content.
+- `SyncToAsyncAdapter._adapter_cache` now prefers the backend object
+  itself as the dict key, with `id()` as a fallback for unhashable
+  backends.
+- `SessionLog.to_list()` includes `recall_key` for full round-trip
+  through checkpoints.
+- `ToolError.context` now round-trips through `Conversation.serialize`
+  / `deserialize`.
+- Permission-denied results from hooks now populate `error_detail` with
+  `ErrorKind.PERMISSION_DENIED` (parity with the `PermissionEngine`
+  path) in both sync and async loops.
+
+### Fixed
+- `_rebuild_prompt` now renders `memory` and falls back to the
+  structured `build_prompt` from `looplet.prompts` instead of a
+  bare f-string, restoring parity with the first-pass build.
+- `_deserialize_message` now reconstructs `ToolError` from serialized
+  `error_kind` / `error_retriable` / `error_context` fields.
+- `_NullSessionLog` (async) gained the attributes the async loop
+  expects: `entries`, `current_theory`, `to_list()`, `compact()`.
+
+## [0.1.5] - initial public import
+
+- Initial release as a standalone package. See the extraction
+  commit history for the pre-extraction development timeline.

looplet-0.1.7/HOOK_GUIDE.md

@@ -0,0 +1,265 @@
+# Hook Authoring Guide
+
+Hooks are the primary extension mechanism in `looplet`. They let you
+inject domain-specific behavior into the generic loop without modifying
+any framework code.
+
+Hooks are [`@runtime_checkable`](https://docs.python.org/3/library/typing.html#typing.runtime_checkable)
+Protocols — **any object with the right methods is a hook**. No base
+class, no registry, no decorator:
+
+```python
+class ConsolePrinter:
+    def post_dispatch(self, state, session_log, tool_call, tool_result, step_num):
+        print(f"#{step_num} {tool_call.tool} → {tool_result.data}")
+        return None
+
+for step in composable_loop(..., hooks=[ConsolePrinter()]):
+    ...
+```
+
+That's the entire contract. Include only the hook methods you need; the
+loop calls the ones you define and ignores the rest.
+
+## The Hook Protocol
+
+A hook is any Python object that implements one or more of these methods:
+
+```python
+class MyHook:
+    def pre_loop(self, state, session_log, context):
+        """Called once at loop start. Setup, logging, initial state."""
+        pass
+
+    def pre_prompt(self, state, session_log, context, step_num) -> str | None:
+        """Called before each LLM prompt. Return text to inject into briefing."""
+        return None
+
+    def pre_dispatch(self, state, session_log, tool_call, step_num) -> ToolResult | None:
+        """Called before each tool. Return a ToolResult to skip execution (cache hit)."""
+        return None
+
+    def post_dispatch(self, state, session_log, tool_call, tool_result, step_num) -> str | None:
+        """Called after each tool. Return text to inject into next prompt."""
+        return None
+
+    def check_done(self, state, session_log, context, step_num) -> str | None:
+        """Called when agent calls done(). Return a string to reject (quality gate)."""
+        return None
+
+    def should_stop(self, state, step_num, new_entities) -> bool:
+        """Called after each step. Return True to force loop termination."""
+        return False
+
+    def on_loop_end(self, state, session_log, context, llm) -> int:
+        """Called once after loop exits. Return count of extra LLM calls made."""
+        return 0
+```
+
+**All methods are optional.** Implement only the ones you need. The loop checks
+for method existence with `hasattr()` before calling.
+
+## Hook Composition
+
+Hooks are passed as a list. All hooks fire in order for each hook point:
+
+```python
+hooks = [LoggingHook(), QualityGateHook(), MetricsHook()]
+composable_loop(llm, tools=reg, hooks=hooks, ...)
+```
+
+- `pre_prompt`: All non-None returns are concatenated into the briefing
+- `pre_dispatch`: First hook to return non-None wins (intercepts the call)
+- `post_dispatch`: All non-None returns are accumulated for the next prompt
+- `check_done`: First hook to return non-None rejects the done() call
+- `should_stop`: First True stops the loop
+
+## Common Hook Patterns
+
+### 1. Progress Tracking
+
+```python
+class ProgressHook:
+    def __init__(self):
+        self.tool_counts: dict[str, int] = {}
+
+    def post_dispatch(self, state, session_log, tool_call, tool_result, step_num):
+        name = tool_call.tool
+        self.tool_counts[name] = self.tool_counts.get(name, 0) + 1
+
+        if tool_result.error:
+            return f"⚠ {name} failed: {tool_result.error[:100]}"
+        return None  # no injection when things go well
+```
+
+### 2. Quality Gate
+
+Prevent the agent from stopping prematurely:
+
+```python
+class MinimumEvidenceGate:
+    def __init__(self, min_tools: int = 3):
+        self.min_tools = min_tools
+
+    def check_done(self, state, session_log, context, step_num):
+        if len(state.steps) < self.min_tools:
+            return (
+                f"Insufficient evidence: only {len(state.steps)} tools called. "
+                f"Call at least {self.min_tools} before concluding."
+            )
+        return None  # allow done()
+```
+
+### 3. Deduplication Warning
+
+Warn when the agent repeats the same tool call:
+
+```python
+class DedupHook:
+    def __init__(self):
+        self._seen: set[str] = set()
+
+    def post_dispatch(self, state, session_log, tool_call, tool_result, step_num):
+        key = f"{tool_call.tool}:{sorted(tool_call.args.items())}"
+        if key in self._seen:
+            return (
+                f"⚠ DUPLICATE: You already called {tool_call.tool} with "
+                f"these args. Try different parameters or a different tool."
+            )
+        self._seen.add(key)
+        return None
+```
+
+### 4. Theory Tracking
+
+Maintain and inject a running theory/hypothesis:
+
+```python
+class TheoryHook:
+    def __init__(self):
+        self.current_theory = "No theory yet"
+
+    def pre_prompt(self, state, session_log, context, step_num):
+        return f"Current working theory: {self.current_theory}"
+
+    def post_dispatch(self, state, session_log, tool_call, tool_result, step_num):
+        # Update theory based on findings
+        theory = tool_call.args.get("__theory__")
+        if theory:
+            self.current_theory = theory
+        return None
+```
+
+### 5. Timeout / Budget Warning
+
+Inject urgency as the budget runs low:
+
+```python
+class BudgetWarningHook:
+    def pre_prompt(self, state, session_log, context, step_num):
+        remaining = state.budget_remaining
+        if remaining <= 2:
+            return "⚠ CRITICAL: Only {remaining} steps left. Wrap up NOW."
+        if remaining <= 5:
+            return f"Budget alert: {remaining} steps remaining."
+        return None
+```
+
+### 6. Domain-Specific Guidance
+
+Inject domain knowledge at specific stages:
+
+```python
+class CodeReviewGuidance:
+    def pre_prompt(self, state, session_log, context, step_num):
+        if step_num == 1:
+            return "Start by listing all changed files to understand scope."
+        if step_num == 3:
+            return "Focus on security-sensitive patterns: auth, crypto, SQL."
+        return None
+```
+
+## Using Built-In Hooks
+
+Cadence ships with several ready-to-use hooks:
+
+```python
+from cadence import (
+    ContextManagerHook,  # Progressive context management
+    StreamingHook,       # Event emission for observability
+    CheckpointHook,      # Auto-save checkpoints
+    TracingHook,         # Span-based tracing
+    MetricsHook,         # Metrics collection
+)
+```
+
+### ContextManagerHook
+
+Prevents context window overflow with three tiers:
+
+```python
+hook = ContextManagerHook(
+    llm,                          # for LLM-based compaction
+    context_window=128_000,       # your model's window size
+    result_max_age_full=3,        # steps before result aging
+    per_result_chars=50_000,      # max chars per result
+    aggregate_chars=500_000,      # max total chars
+)
+```
+
+### StreamingHook
+
+Emits typed events for real-time observability:
+
+```python
+from cadence import StreamingHook, CallbackEmitter
+
+def on_event(event):
+    print(f"[{event.event_type}] {event}")
+
+hook = StreamingHook(CallbackEmitter(on_event))
+```
+
+## Async Hooks
+
+For the async loop, implement the same methods as `async def`:
+
+```python
+class AsyncProgressHook:
+    async def post_dispatch(self, state, session_log, tool_call, tool_result, step_num):
+        await save_to_database(tool_call, tool_result)
+        return None
+```
+
+The async loop checks `asyncio.iscoroutinefunction()` and properly `await`s
+async hooks while also supporting sync hooks in the same hook list.
+
+## Testing Hooks
+
+Hooks are plain Python classes — test them in isolation:
+
+```python
+def test_quality_gate_rejects_early():
+    hook = MinimumEvidenceGate(min_tools=3)
+    state = MockState(steps=[1, 2])  # only 2 steps
+    result = hook.check_done(state, None, None, 2)
+    assert result is not None  # should reject
+    assert "Insufficient" in result
+
+def test_quality_gate_allows_enough():
+    hook = MinimumEvidenceGate(min_tools=3)
+    state = MockState(steps=[1, 2, 3])  # enough
+    result = hook.check_done(state, None, None, 3)
+    assert result is None  # should allow
+```
+
+---
+
+## Related: provenance hook
+
+`TrajectoryRecorder` (in `looplet.provenance`) is a hook that
+captures a complete structured record of every loop run —
+`pre_loop` → `pre_prompt` → `post_dispatch` → `on_loop_end` — and
+serialises it to disk alongside per-LLM-call prompt/response files.
+Use it whenever you want a git-diffable audit trail of what your
+agent did. See [PROVENANCE_GUIDE.md](PROVENANCE_GUIDE.md).