@kontourai/flow-agents 0.1.1 → 0.2.0

package/docs/index.md

@@ -4,12 +4,12 @@ title: Kontour Flow Agents
 
 # Flow Agents
 
-<p class="home-lede">Coding agents are powerful and forgetful. Flow Agents wraps Codex, Claude Code, Kiro, and CI agents in an operating layer that keeps long-running work inspectable — from idea to release readiness — so you ask for outcomes and the system supplies the path, the state, the checks, and the proof.</p>
+<p class="home-lede">A portable process-discipline layer for agentic work: canonical policies, evidence, and telemetry that compile to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next. Flow Agents keeps work inspectable from idea to release readiness so you ask for outcomes and the system supplies the path, the state, the checks, and the proof.</p>
 
 <div class="value-grid">
   <section>
-    <strong>Stay on the path</strong>
-    <span>Turn loose requests into shaped work, plans, implementation waves, review, verification, evidence, and release decisions — the same workflow in every supported runtime.</span>
+    <strong>Four canonical policies</strong>
+    <span>Workflow steering, quality gate, stop-goal-fit, and config protection — each a canonical script under <code>scripts/hooks/</code> that compiles to the host's native hook format. Claude Code and Codex are the L2 reference implementations.</span>
   </section>
   <section>
     <strong>Survive context loss</strong>
@@ -41,7 +41,29 @@ flowchart LR
   Evidence -->|not verified| Plan
 ```
 
-Flow Agents adds the operating layer around the model: skills choose the right workflow, sidecars preserve state, hooks catch stop-short behavior, and evals keep the bundle honest as it changes. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>; Flow Agents makes that enforcement native inside agent harnesses.
+Flow Agents adds the operating layer around the model: skills choose the right workflow, sidecars preserve state, hooks enforce the four canonical policies, and evals keep the bundle honest as it changes. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>; Flow Agents compiles those policies to whatever hook surface a host exposes.
+
+## Process-discipline layer
+
+The four canonical policy classes are defined in the <a href="spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> using a runtime-neutral vocabulary. Adapters translate them to the host's native hook format at three conformance levels: <strong>L0</strong> (telemetry only), <strong>L1</strong> (steering + stop-goal-fit warning), and <strong>L2</strong> (all four policies with blocking capability).
+
+### Runtime and support matrix
+
+| Tier | Runtime | Ships | Conformance |
+| --- | --- | --- | --- |
+| Core harness | Claude Code | install + hooks + bundle | L2 — reference implementation |
+| Core harness | Codex | install + hooks + bundle | L2 — reference implementation |
+| Core harness | Kiro | install + hooks + bundle | L2 |
+| Core harness | opencode | agents, skills, plugin, opencode.json | L1 — no prompt-submit hook |
+| Core harness | pi | extension, skills, AGENTS.md | L1 — no stop hook |
+| Official framework adapter | AWS Strands (Python) | `integrations/strands/` spike/preview | L0 + config protection via cancellation |
+| Conformance-certified | Community / third-party | Self-certify | Conformance kit in development |
+
+Documented gaps: opencode has no native `prompt.submit`-equivalent event; pi has no stop hook; Codex live hook influence on model context is limited. The <a href="spec/runtime-hook-surface.html">Runtime Hook Surface spec</a> names every gap explicitly using the canonical event taxonomy.
+
+## Framework adapters
+
+The same canonical policies wire into agent frameworks as in-process language-native packages. `integrations/strands/` contains `flow-agents-strands`, a Python `HookProvider` that emits the canonical telemetry taxonomy and enforces config protection via `BeforeToolCallEvent` cancellation — 50 unit tests, no Strands SDK required. This is a spike/preview. See <a href="spec/runtime-hook-surface.html">the spec</a> for the full framework adapter mapping and minimum viable adapter pseudocode.
 
 ## Quick Start
 
@@ -49,7 +71,13 @@ Flow Agents adds the operating layer around the model: skills choose the right w
 npx @kontourai/flow-agents init --dest /path/to/workspace
 ```
 
-Until the first npm release lands, the same command works from a checkout: clone the repo, `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
+Runtime-specific installs:
+
+```bash
+npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
+npx @kontourai/flow-agents init --runtime opencode --dest /path/to/workspace --yes
+npx @kontourai/flow-agents init --runtime pi --dest /path/to/workspace --yes
+```
 
 Then ask for the workflow you want, in plain language:
 
@@ -78,6 +106,14 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Workflow Map</strong>
     <span>See the core skills, gates, artifacts, and route-back behavior.</span>
   </a>
+  <a class="doc-card" href="spec/runtime-hook-surface.html">
+    <strong>Runtime Hook Surface</strong>
+    <span>Canonical event taxonomy, four policy classes, conformance levels L0/L1/L2, and host mapping tables for adapter authors.</span>
+  </a>
+  <a class="doc-card" href="vision.html">
+    <strong>Vision and Direction</strong>
+    <span>Where Flow Agents is going: kits beyond coding, TypeScript framework adapters, and Kontour Console as the unifying telemetry surface.</span>
+  </a>
   <a class="doc-card" href="north-star.html">
     <strong>North Star</strong>
     <span>The product promise, design principles, operating layers, and roadmap.</span>
@@ -118,11 +154,15 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Developer Reference</strong>
     <span>The generated repo map: commands, agents, skills, scripts, and contracts.</span>
   </a>
+  <a class="doc-card" href="integrations/index.html">
+    <strong>Integration Examples</strong>
+    <span>Worked examples for harness runtimes (Claude Code, opencode, pi), framework adapters (AWS Strands), and third-party self-certification with the conformance kit.</span>
+  </a>
 </div>
 
 ## The Kontour family
 
-Kontour AI shows the work behind AI. <a href="https://kontourai.github.io/flow/">Flow</a> proves why a process was allowed to advance. Veritas makes AI-authored code changes inspectable. Flow Agents packages those foundations into the agent tools you already use — so trustworthy autonomy doesn't require a perfect prompt, perfect memory, or a new runtime.
+Kontour AI shows the work behind AI. <a href="https://kontourai.github.io/flow/">Flow</a> proves why a process was allowed to advance. <a href="https://kontourai.io/veritas">Veritas</a> makes AI-authored code changes inspectable. <a href="https://kontourai.io/survey">Survey</a> and <a href="https://kontourai.io/surface">Surface</a> carry the evidence underneath. Flow Agents packages those foundations into the agent tools you already use — so trustworthy autonomy doesn't require a perfect prompt, perfect memory, or a new runtime.
 
 ## Why it matters
 

package/docs/integrations/conformance.md

@@ -0,0 +1,246 @@
+---
+title: Conformance
+---
+
+# Conformance
+
+This page explains how a third-party adapter self-certifies against the Flow Agents policy engine contract. It covers the engine contract version 1.0, how to run the conformance kit, what each conformance level requires, and how to declare gaps using the opencode and pi built-in examples as the pattern.
+
+Everything in this page is grounded in `packaging/conformance/` and `docs/spec/runtime-hook-surface.md`. No behavior is inferred.
+
+## Engine contract 1.0
+
+The engine contract is the versioned public interface between Flow Agents policy scripts and adapters. Third-party adapters bind to this contract. Breaking changes will increment the major version and be announced via CHANGELOG.
+
+The contract is defined in <a href="../spec/runtime-hook-surface.html">the spec, section 8</a>. In summary:
+
+**Invocation — subprocess form** (standard, used by all current adapters):
+
+```bash
+echo '<JSON payload>' | node scripts/hooks/run-hook.js <hookId> <scriptRelativePath> [profilesCsv]
+```
+
+- `hookId`: identifier for the hook (e.g., `config-protection`). Used for profile/disable checks.
+- `scriptRelativePath`: path relative to `scripts/hooks/` (e.g., `config-protection.js`).
+- `profilesCsv`: comma-separated profile names. Hooks not in the current `SA_HOOK_PROFILE` are skipped.
+- Payload is read from stdin. Max 1 MiB. If truncated, `SA_HOOK_INPUT_TRUNCATED=1` is set.
+
+**Invocation — native import form** (for Node.js adapters, preferred for performance):
+
+```javascript
+const { run } = require('./scripts/hooks/config-protection.js');
+const output = run(rawJsonString, { truncated: false, maxStdin: 1024 * 1024 });
+```
+
+All four policy scripts export `module.exports = { run }`.
+
+**Version query:**
+
+```bash
+node scripts/hooks/run-hook.js --contract-version
+# → {"contract_version":"1.0","runner":"run-hook.js"}
+```
+
+**Exit code semantics:**
+
+| Exit code | Semantics |
+| --- | --- |
+| `0` | Allow — policy has no objection |
+| `2` | Block — policy vetoes the action |
+| other | Error — treat as allow (fail-open) |
+
+**Fail-open rule**: Hook runtime errors must never block agent work. Every policy except `config-protection` exits 0 always on non-policy errors. `config-protection` exits 2 only on a protected file match or a truncated payload; runtime errors exit 0.
+
+## What each conformance level requires
+
+Conformance levels are defined in <a href="../spec/runtime-hook-surface.html">the spec, section 4</a>.
+
+### L0: Telemetry only
+
+The adapter wires the telemetry script to at least one lifecycle event. No policy hooks are required.
+
+**Required:** At minimum, `agentSpawn` telemetry fires on session start.
+
+**Permitted gaps:** All four policy classes (workflow steering, quality gate, stop-goal-fit, config protection) may be absent.
+
+**Use case:** Framework adapters and runtimes where the telemetry signal is valuable but blocking or context injection is not feasible.
+
+### L1: Steering
+
+The adapter implements L0 plus workflow steering and stop-goal-fit in warning mode.
+
+**Required:**
+- L0 telemetry.
+- Workflow steering fires on `userPromptSubmit` (or the closest equivalent — document which event is used and any fidelity loss).
+- Stop-goal-fit fires on `stop` in warning-only mode (exits 0 always).
+
+**Permitted gaps:** Quality gate and config protection may be absent. Stop-goal-fit runs in warning mode only.
+
+**Use case:** Harness adapters where the runtime supports prompt-submit and stop hooks, but tool-level blocking is not available or desired.
+
+### L2: Enforcing gates
+
+The adapter implements L1 plus all blocking policy classes.
+
+**Required:**
+- L1 steering and stop telemetry.
+- Config protection fires on `preToolUse` and can block (exit 2 translates to a deny response).
+- Quality gate fires on `postToolUse`.
+- Stop-goal-fit fires on `stop` with `FLOW_AGENTS_GOAL_FIT_STRICT` configurable.
+
+**Permitted gaps:** None. All four policy classes must be wired. Any missing host trigger must be documented as a named gap in the conformance declaration.
+
+**Use case:** Claude Code and Codex are L2 reference implementations.
+
+## Running the conformance kit
+
+The conformance kit is in `packaging/conformance/`. It requires no npm dependencies — only Node.js.
+
+**Self-test the canonical engine (must report L2):**
+
+```bash
+node packaging/conformance/run-conformance.js --self
+```
+
+**Test a third-party adapter at L2:**
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L2
+```
+
+**Test at L1 only:**
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node /path/to/your-adapter.js" \
+  --level L1
+```
+
+**CLI reference:**
+
+```
+node packaging/conformance/run-conformance.js [options]
+
+  --self              Run against the canonical engine (target L2)
+  --adapter-cmd CMD   Shell command to pipe fixtures to (adapter under test)
+  --level L0|L1|L2    Minimum conformance level to enforce (default: L2 for --self, L0 for --adapter-cmd)
+  --fixtures DIR      Override fixture directory (default: packaging/conformance/fixtures/)
+  --verbose           Print fixture payloads and full output in per-fixture results
+```
+
+Exit codes: `0` = target level reached, `1` = target level not reached, `2` = usage error.
+
+### Adapter contract for the runner
+
+Your adapter command:
+- Receives a canonical JSON payload on stdin (one JSON object).
+- Writes the input JSON (or augmented form) to stdout on allow.
+- Exits `0` to allow, `2` to block, any other code for error (treated as allow, fail-open).
+
+The runner invokes your command exactly once per fixture via `sh -c "<your-cmd>"`.
+
+### Fixture inventory
+
+The fixtures in `packaging/conformance/fixtures/` cover all four policy classes:
+
+| Fixture | Policy class | Event | Level |
+| --- | --- | --- | --- |
+| `config-protection--block-eslintrc.json` | config-protection | preToolUse | L2 |
+| `config-protection--block-biome.json` | config-protection | preToolUse | L2 |
+| `config-protection--allow-safe-file.json` | config-protection | preToolUse | L2 |
+| `config-protection--allow-no-path.json` | config-protection | preToolUse | L2 |
+| `quality-gate--allow-nonexistent-file.json` | quality-gate | postToolUse | L2 |
+| `quality-gate--allow-no-path.json` | quality-gate | postToolUse | L2 |
+| `stop-goal-fit--allow-clean-cwd.json` | stop-goal-fit | stop | L1 |
+| `stop-goal-fit--warn-active-delivery.json` | stop-goal-fit | stop | L1 |
+| `stop-goal-fit--block-strict-mode.json` | stop-goal-fit | stop | L2 |
+| `workflow-steering--allow-no-state.json` | workflow-steering | userPromptSubmit | L1 |
+| `workflow-steering--inject-active-state.json` | workflow-steering | userPromptSubmit | L1 |
+| `workflow-steering--inject-subagent-steering.json` | workflow-steering | postToolUse | L1 |
+
+Fixtures with `workspace_setup` create a temporary directory with the listed files before invoking the adapter and clean up afterward. The `cwd` field in those payloads is replaced with the temp directory path at runtime.
+
+## How to declare gaps
+
+If your adapter legitimately cannot satisfy a fixture — because the host runtime has no blocking `preToolUse` equivalent, or no stop hook — declare the gap explicitly in your adapter documentation. The opencode and pi adapters are the reference pattern.
+
+### opencode: no prompt-submit hook
+
+opencode has no native `prompt.submit`-equivalent event. Workflow steering cannot fire at each user turn. The gap is declared in the plugin source comment and in the conformance declaration:
+
+```yaml
+conformance_level: L1
+host: opencode
+event_coverage:
+  agentSpawn: session.created (full fidelity)
+  userPromptSubmit: no native equivalent — workflow steering fires at session.created only
+  preToolUse: tool.execute.before (full fidelity, blocking available via thrown Error)
+  postToolUse: tool.execute.after (full fidelity)
+  stop: session.idle (reduced fidelity — fires on idle, not on completion)
+  permissionRequest: permission.asked (telemetry only — no blocking capability)
+policy_coverage:
+  workflow_steering: partial — injected at session.created only, not at each turn
+  quality_gate: wired at tool.execute.after
+  stop_goal_fit: degraded — session.idle does not reliably fire at completion
+  config_protection: wired at tool.execute.before (blocking)
+gaps:
+  - event: userPromptSubmit
+    reason: opencode has no prompt.submit equivalent
+    degradation: Workflow steering fires once at session.created instead of at each user turn
+  - event: stop
+    reason: session.idle is the closest event but is not a true completion signal
+    degradation: stop-goal-fit warnings may not fire reliably at session end
+```
+
+### pi: no stop hook
+
+pi has no stop hook. Stop-goal-fit cannot fire at session end. The gap is declared in the extension source comment and in the conformance declaration:
+
+```yaml
+conformance_level: L1
+host: pi
+event_coverage:
+  agentSpawn: session_start (full fidelity)
+  userPromptSubmit: before_agent_start (reduced fidelity — fires at agent start, not per-turn)
+  preToolUse: tool_call (full fidelity, blockable via return { block: true })
+  postToolUse: tool_result (full fidelity)
+  stop: no native equivalent — session_shutdown used as closest analogue
+policy_coverage:
+  workflow_steering: partial — injected at before_agent_start, not at each user turn
+  quality_gate: wired at tool_result
+  stop_goal_fit: degraded — session_shutdown does not reliably carry stop semantics
+  config_protection: wired at tool_call (blocking)
+gaps:
+  - event: stop
+    reason: pi has no stop hook
+    degradation: stop-goal-fit cannot fire; agent may complete without the check
+    workaround: Run stop-goal-fit checks explicitly in CI or via a post-session script
+```
+
+## Including a conformance declaration in your adapter
+
+After running the conformance kit, include a declaration in your adapter documentation:
+
+```yaml
+conformance_level: L2          # or L0 / L1
+engine_contract_version: "1.0"
+runner_version: "run-conformance.js"
+test_date: 2026-06-11
+verdict: PASS
+fixture_count: 12
+fixtures_passed: 12
+gaps: []
+```
+
+If any fixtures fail, list them under `gaps` with a description of the degradation behavior. Declared gaps do not prevent reaching a lower conformance level — they make the adapter's behavior honest and auditable.
+
+## Related references
+
+- `packaging/conformance/run-conformance.js` — conformance runner
+- `packaging/conformance/fixtures/` — golden fixtures
+- `packaging/conformance/README.md` — conformance kit README
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec §8</a> — engine contract 1.0 in full
+- <a href="harness-install.html">Harness Install</a> — worked install examples for opencode and pi
+- <a href="framework-adapter.html">Framework Adapter</a> — worked example of a language-native adapter

package/docs/integrations/framework-adapter.md

@@ -0,0 +1,275 @@
+---
+title: Framework Adapter
+---
+
+# Framework Adapter
+
+This page walks through the `integrations/strands/` reference implementation: a Python `HookProvider` for AWS Strands Agents. It covers how to construct `FlowAgentsHooks`, what telemetry it emits, how the policy gate binds to the canonical engine contract, and the documented limitations of this spike.
+
+Everything in this page is grounded in the files under `integrations/strands/`. No behavior is inferred or aspirational unless explicitly labeled as direction.
+
+## Harness adapters vs. framework adapters
+
+Harness adapters (Claude Code, Codex, Kiro, opencode, pi) integrate with coding-agent runtimes that have their own hook format: JSON on stdin, exit codes, and lifecycle events named by the harness. Each harness adapter normalizes its runtime's hook payloads into the canonical Flow Agents telemetry taxonomy and delegates to `scripts/telemetry/telemetry.sh`.
+
+Framework adapters are in-process packages. Strands Agents is not a coding-agent harness — it is a general-purpose Python agent SDK. Its hook surface (`HookProvider` / `HookRegistry`) is class-based and synchronous. There is no stdin/stdout protocol and no process exit codes as block signals. Hook callbacks receive typed Python event objects and can mutate them in place.
+
+Despite the surface differences, the same canonical event taxonomy is used. The JSONL output from `FlowAgentsHooks` is structurally identical to the output produced by `claude-telemetry-hook.js` and `codex-telemetry-hook.js`.
+
+## Constructing FlowAgentsHooks
+
+`FlowAgentsHooks` is the main entry point. It implements the Strands `HookProvider` protocol via duck typing, so `strands-agents` is not required at import time.
+
+```python
+from flow_agents_strands import FlowAgentsHooks
+
+hooks = FlowAgentsHooks(
+    workspace=".",           # root of your project (reads .flow-agents/)
+    agent_name="my-agent",   # appears in telemetry events
+)
+```
+
+Constructor parameters (all optional):
+
+| Parameter | Default | Purpose |
+| --- | --- | --- |
+| `sink_path` | `<workspace>/.flow-agents/.telemetry/full.jsonl` | JSONL telemetry output path or directory |
+| `workspace` | `os.getcwd()` | Root of the workspace; used to discover `.flow-agents/` |
+| `agent_name` | `"strands-agent"` | Agent identifier embedded in telemetry events |
+| `runtime` | `"strands"` | Runtime label embedded in telemetry events |
+| `policy_gate` | `PolicyGate()` | Optional custom `PolicyGate` instance (for testing) |
+
+`FlowAgentsHooks` is usable without `strands-agents` installed. Telemetry emission and `steering_context()` work in any Python environment. The `register_hooks` method (which wires callbacks into a `HookRegistry`) requires `strands-agents` and raises `ImportError` if the SDK is absent.
+
+## Wiring into an Agent
+
+```python
+from strands import Agent
+from strands.models import BedrockModel
+from flow_agents_strands import FlowAgentsHooks
+
+hooks = FlowAgentsHooks(workspace=".")
+
+# Load steering context BEFORE constructing the agent.
+# Strands' BeforeInvocationEvent does not expose a mutable system prompt,
+# so steering must be injected at construction time.
+system_prompt = (
+    "You are a helpful assistant.\n"
+    + hooks.steering_context()
+)
+
+model = BedrockModel(model_id="anthropic.claude-3-5-sonnet-20241022-v2:0")
+agent = Agent(model=model, system_prompt=system_prompt, hooks=[hooks])
+
+result = agent("List the files in this directory.")
+```
+
+`register_hooks` is called by the Strands runtime when `hooks=[hooks]` is passed to `Agent`. It registers five callbacks:
+
+| Strands event | Canonical event | What fires |
+| --- | --- | --- |
+| `AgentInitializedEvent` | `agentSpawn` | `emit_session_start()` — records `session.start` |
+| `BeforeInvocationEvent` | `userPromptSubmit` | `emit("userPromptSubmit")` — records `turn.user` |
+| `AfterInvocationEvent` | `stop` | `emit_session_end(duration_s=…)` — records `session.end` |
+| `BeforeToolCallEvent` | `preToolUse` | Telemetry + policy gate (config-protection) |
+| `AfterToolCallEvent` | `postToolUse` | `emit_tool_result(…)` — records `tool.result` |
+
+This mapping is the `STRANDS_TO_CANONICAL` dict exposed at module level by `integrations/strands/flow_agents_strands/telemetry.py`:
+
+```python
+STRANDS_TO_CANONICAL = {
+    "AgentInitializedEvent":  "agentSpawn",
+    "BeforeInvocationEvent":  "userPromptSubmit",
+    "AfterInvocationEvent":   "stop",
+    "BeforeToolCallEvent":    "preToolUse",
+    "AfterToolCallEvent":     "postToolUse",
+    "AfterModelCallEvent":    "postToolUse",   # closest analogue; no tool name
+    "MessageAddedEvent":      "userPromptSubmit",
+}
+```
+
+## Telemetry emitted
+
+Events are written to `.flow-agents/.telemetry/full.jsonl` by default. The record shape matches `build_base_event()` in `scripts/telemetry/telemetry.sh`:
+
+```json
+{
+  "schema_version": "0.3.0",
+  "timestamp": "1718000000000",
+  "session_id": "<uuid>",
+  "event_id": "<uuid>",
+  "event_type": "tool.invoke",
+  "agent": { "name": "my-agent", "runtime": "strands", "version": "unknown" },
+  "hook": {
+    "event_name": "preToolUse",
+    "source": "strands",
+    "stop_hook_active": null,
+    "raw_input": null
+  },
+  "tool": { "name": "edit", "normalized_name": "fs_write", "input": { ... } }
+}
+```
+
+Canonical names map to schema `event_type` values via `_CANONICAL_TO_SCHEMA` in `telemetry.py`:
+
+| Canonical name | Schema event_type |
+| --- | --- |
+| `agentSpawn` | `session.start` |
+| `userPromptSubmit` | `turn.user` |
+| `preToolUse` | `tool.invoke` |
+| `permissionRequest` | `tool.permission_request` |
+| `postToolUse` | `tool.result` |
+| `stop` | `session.end` |
+
+Telemetry is always fail-open: if the JSONL file cannot be written (`OSError`), the exception is swallowed silently. Telemetry must never block agent work.
+
+## Policy gate: config-protection
+
+The config-protection policy binds to the canonical Node.js engine via subprocess. The binding is in `integrations/strands/flow_agents_strands/policy.py` in the `PolicyGate` class.
+
+**Primary mode — engine subprocess:**
+
+On `BeforeToolCallEvent`, if the tool name is a write-like tool (one of `edit`, `write`, `fs_write`, `apply_patch`, `create_file`, `str_replace_editor`), the gate serializes the event to a canonical JSON payload and spawns:
+
+```bash
+echo '{"hook_event_name":"PreToolUse","tool_name":"edit","tool_input":{"path":"biome.json"}}' \
+  | node scripts/hooks/run-hook.js config-protection config-protection.js
+```
+
+The engine exits 2 (block) or 0 (allow). Exit code 2 causes `event.cancel_tool` to be set to the block reason from stderr. Strands cancels the call and surfaces the message as the tool result. All other exit codes fail open.
+
+The engine is located by `_find_engine_paths()` in this priority order:
+
+1. `FLOW_AGENTS_ENGINE_PATH` environment variable (explicit override).
+2. Relative to the package source file: `../../../../scripts/hooks/run-hook.js` (works from a repo checkout).
+3. Walked up from `os.getcwd()` looking for `node_modules/@kontourai/flow-agents/scripts/hooks/run-hook.js` (npm-installed package).
+
+**Fallback mode — Python evaluation:**
+
+If `node` is not on PATH or `run-hook.js` cannot be located, the gate degrades to a built-in Python implementation of the same logic and emits a one-time `RuntimeWarning`. The Python fallback uses the same `PROTECTED_FILES` frozenset as `config-protection.js` and is auditable. This is not silent: the warning is printed once to stderr.
+
+**Custom protected set:**
+
+If a `PolicyGate` is constructed with a custom `protected_files` frozenset, Python evaluation is used directly (the engine subprocess cannot receive a runtime-custom set). This path is intended for tests and local override only.
+
+## Workflow steering
+
+Strands' `BeforeInvocationEvent` does not expose a mutable system prompt at callback time.
+
+The spike approach: call `hooks.steering_context()` at `Agent` construction time and append the result to the system prompt. `steering_context()` reads the current workflow state from `.flow-agents/` and returns a text block. It also emits a `turn.user` telemetry event so the injection is recorded in the JSONL log.
+
+This is a one-shot snapshot. It does not re-evaluate on every turn the way `workflow-steering.js` does at `UserPromptSubmit`. See the Limitations section for the productization path.
+
+## Documented limitations
+
+The following limitations are from `integrations/strands/README.md` and reflect the current spike state. They are not defects to be worked around silently — they are honest gaps.
+
+1. **Node.js subprocess dependency**: The primary policy binding spawns a Node.js subprocess for each `BeforeToolCallEvent` involving a write-like tool. If `node` is not on PATH or the package is not installed, the gate degrades to the Python fallback with a one-time `RuntimeWarning`. To force the subprocess path, set `FLOW_AGENTS_ENGINE_PATH` to the absolute path of `run-hook.js`.
+
+2. **Steering seam**: Strands does not allow mutating the system prompt from `BeforeInvocationEvent`. The workaround (`steering_context()` at Agent construction) is a one-shot snapshot; it does not re-evaluate on every turn. Productization would require either a custom Strands model wrapper that injects context per-turn, or upstream SDK support for mutable system-prompt context in the invocation event.
+
+3. **session.usage event omitted**: The JS harness emits a `session.usage` event on stop with token counts. The Strands `AfterInvocationEvent` does not expose token-usage data in the hook payload, so this event is not emitted.
+
+4. **No analytics channel**: The harness adapters write to two channels (full + analytics) with different redaction profiles. This spike writes only to the `full` channel.
+
+5. **No Console/HTTP sink**: The bash transport supports POSTing events to a Console endpoint. This adapter writes JSONL only.
+
+6. **Runtime version is "unknown"**: Strands does not expose its version through the hook event; `agent.version` is hardcoded to `"unknown"`.
+
+7. **No subagent/delegation event**: The Strands SDK does not have a built-in delegation tool; the `subagentStart`/`subagentStop` telemetry path is not wired.
+
+8. **Quality-gate policy omitted**: `quality-gate.js` invokes ruff/biome after edits. There is no clear Strands analogue yet.
+
+## Conformance declaration
+
+The Strands adapter is L0 plus config protection via `BeforeToolCallEvent` cancellation. A full conformance declaration would read:
+
+```
+conformance_level: L0  (+ config-protection via BeforeToolCallEvent)
+host: AWS Strands Agents
+event_coverage:
+  agentSpawn: AgentInitializedEvent (full fidelity)
+  userPromptSubmit: BeforeInvocationEvent (no per-turn injection — spike limitation)
+  preToolUse: BeforeToolCallEvent (full fidelity, cancellable)
+  postToolUse: AfterToolCallEvent (full fidelity)
+  stop: AfterInvocationEvent (full fidelity)
+  permissionRequest: no native equivalent
+  subagentStart: no native equivalent
+  subagentStop: no native equivalent
+policy_coverage:
+  workflow_steering: partial — injected once at Agent construction, not per-turn
+  quality_gate: omitted — no current Strands analogue
+  stop_goal_fit: omitted — AfterInvocationEvent used for telemetry only
+  config_protection: wired at BeforeToolCallEvent (blocking via event.cancel_tool)
+```
+
+## Running tests
+
+The spike ships 50 unit tests that require no Strands SDK:
+
+```bash
+cd integrations/strands
+python3 -m unittest discover
+```
+
+## Related references
+
+- `integrations/strands/flow_agents_strands/hooks.py` — `FlowAgentsHooks` and `register_hooks`
+- `integrations/strands/flow_agents_strands/telemetry.py` — `TelemetrySink`, `STRANDS_TO_CANONICAL`
+- `integrations/strands/flow_agents_strands/policy.py` — `PolicyGate`, engine subprocess binding
+- `integrations/strands/flow_agents_strands/steering.py` — `SteeringContext`
+- `integrations/strands/README.md` — spike README with quickstart and full limitations list
+- <a href="../spec/runtime-hook-surface.html">Runtime Hook Surface spec §6.2</a> — framework adapter contract and minimum viable adapter pseudocode
+- <a href="conformance.html">Conformance</a> — how to self-certify using the conformance kit
+
+---
+
+## TypeScript native-import adapter (`integrations/strands-ts/`)
+
+`@kontourai/flow-agents-strands` is the first **native-import** consumer of the policy engine contract. Where the Python adapter spawns a subprocess for each `BeforeToolCallEvent` policy check, the TS adapter calls `config-protection.js`'s exported `run()` function directly — zero subprocess overhead on the hot path.
+
+### Key differences from the Python adapter
+
+| | Python adapter | TypeScript adapter |
+|--|----------------|-------------------|
+| Engine binding | subprocess (`node run-hook.js …`) | `require("config-protection.js").run()` — in-process |
+| Strands SDK | `register_hooks(registry)` → `registry.add_callback` | `registerHooks(registry)` → `registry.addCallback` |
+| Cancel signal | `event.cancel_tool = reason` | `event.cancel = reason` (TS variant) |
+| Conformance | L0 + config-protection | L2 (all four policy classes via shim) |
+| Test framework | stdlib unittest (Python) | node:test (no extra deps) |
+
+### Constructing FlowAgentsHooks (TypeScript)
+
+```typescript
+import { FlowAgentsHooks } from "@kontourai/flow-agents-strands";
+
+const hooks = new FlowAgentsHooks({
+  workspace: ".",        // root of your project
+  agentName: "my-agent",
+  // engineRoot: "/path/to/flow-agents"  // optional: explicit engine path
+});
+```
+
+### Event mapping
+
+The TS adapter exports `STRANDS_TO_CANONICAL` matching the Python adapter's dict:
+
+| Strands TS Event | Canonical event |
+|------------------|-----------------|
+| `BeforeInvocationEvent` | `userPromptSubmit` |
+| `AfterInvocationEvent` | `stop` |
+| `BeforeToolCallEvent` | `preToolUse` |
+| `AfterToolCallEvent` | `postToolUse` |
+| `AgentInitializedEvent` | `agentSpawn` |
+
+### Conformance
+
+The TS adapter achieves **L2** via `bin/conformance-shim.mjs`:
+
+```bash
+node packaging/conformance/run-conformance.js \
+  --adapter-cmd "node integrations/strands-ts/bin/conformance-shim.mjs" \
+  --level L2
+```
+
+12/12 fixtures pass. See `integrations/strands-ts/README.md` for the full conformance declaration and limitations.