@kontourai/flow-agents 0.1.1 → 0.2.0

package/.github/dependabot.yml

@@ -0,0 +1,23 @@
+# Keeps pinned dependencies current; the runtime-compat workflow separately
+# canaries LATEST runtime binaries and framework SDKs on a weekly cron.
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        dependency-type: development
+  - package-ecosystem: npm
+    directory: "/integrations/strands-ts"
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip
+    directory: "/integrations/strands"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

package/.github/workflows/publish-npm.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
-          node-version: "22"
+          node-version: "24"
           registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies

package/.github/workflows/release-please.yml

@@ -0,0 +1,31 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@v4
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+      # Tags created with GITHUB_TOKEN do not trigger tag-push workflows, so
+      # dispatch the existing publish pipeline at the new tag explicitly.
+      - name: Dispatch publish workflow
+        if: steps.release.outputs.release_created == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh workflow run publish-npm.yml --repo "$GITHUB_REPOSITORY" --ref "${{ steps.release.outputs.tag_name }}"

package/.github/workflows/runtime-compat.yml

@@ -0,0 +1,118 @@
+name: Runtime Compatibility
+
+# Weekly canary against the LATEST released versions of supported host
+# runtimes and framework SDKs. Catches upstream drift (config schema changes,
+# plugin/extension API changes, SDK breaking releases) before users do.
+#
+# Report-only: failures open/refresh a tracking issue; they do not block CI.
+# Live model loops are out of scope here (no provider credentials in CI) —
+# coverage is install + config acceptance + plugin/extension load + the
+# mechanical hook chain, which is where every upstream break found so far
+# (opencode config schema, plugin spawn semantics, pi extension parsing)
+# would have surfaced.
+
+on:
+  schedule:
+    - cron: "17 6 * * 1" # Mondays 06:17 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  harness-canary:
+    name: Harness canary (${{ matrix.runtime }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runtime: opencode
+            install: npm install -g opencode-ai@latest
+            version: opencode --version
+          - runtime: pi
+            install: npm install -g @earendil-works/pi-coding-agent@latest
+            version: pi --version
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+
+      - name: Install latest ${{ matrix.runtime }}
+        run: |
+          ${{ matrix.install }}
+          ${{ matrix.version }}
+
+      - name: Build bundles
+        run: npm run build:bundles
+
+      - name: Mechanical hook chain (lifecycle suite)
+        run: bash evals/integration/test_bundle_lifecycle.sh
+
+      - name: Live harness (binary-gated, provider assertions skip)
+        run: bash evals/acceptance/test_${{ matrix.runtime }}_harness.sh
+
+  framework-sdk-canary:
+    name: Framework SDK canary
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Root install + build
+        run: |
+          npm ci
+          npm run build
+
+      - name: Strands TS adapter against latest @strands-agents/sdk
+        run: |
+          cd integrations/strands-ts
+          npm view @strands-agents/sdk version
+          npm test
+          npm run conformance
+
+      - name: Strands Python adapter against latest strands-agents
+        run: |
+          python3 -m venv /tmp/sdk-canary
+          /tmp/sdk-canary/bin/pip install -q strands-agents
+          /tmp/sdk-canary/bin/pip show strands-agents | head -2
+          cd integrations/strands
+          /tmp/sdk-canary/bin/python -m unittest discover
+
+  report:
+    name: Open tracking issue on failure
+    runs-on: ubuntu-latest
+    needs: [harness-canary, framework-sdk-canary]
+    if: failure()
+    steps:
+      - name: Create or comment on tracking issue
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TITLE="Runtime compatibility canary failed ($(date -u +%Y-%m-%d))"
+          BODY="The weekly runtime/SDK canary failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+
+          One or more of: latest opencode, latest pi, latest @strands-agents/sdk, latest strands-agents (Python) broke install, hook-chain, harness, adapter tests, or conformance. Triage the run logs and either fix the adapter or document the gap in the conformance declaration."
+          EXISTING=$(gh issue list --repo "${{ github.repository }}" --search "Runtime compatibility canary failed in:title state:open" --json number --jq '.[0].number // empty')
+          if [ -n "$EXISTING" ]; then
+            gh issue comment "$EXISTING" --repo "${{ github.repository }}" --body "$BODY"
+          else
+            gh issue create --repo "${{ github.repository }}" --title "$TITLE" --body "$BODY" --label upstream-drift
+          fi

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.2.0](https://github.com/kontourai/flow-agents/compare/v0.1.2...v0.2.0) (2026-06-11)
+
+
+### Features
+
+* engine contract 1.0, conformance kit, Strands rebind, integration docs ([fd94f58](https://github.com/kontourai/flow-agents/commit/fd94f583f52c874d901e06da0ee338830b3d469a))
+* install lifecycle tests, dogfood command, collision marker fix ([a0fb2e3](https://github.com/kontourai/flow-agents/commit/a0fb2e31d897426db435801c8a637a9736d99ad1))
+* live acceptance harnesses for opencode and pi ([181382b](https://github.com/kontourai/flow-agents/commit/181382b8dfe05cce41c0471a030e7d795950cd09))
+* Strands TypeScript adapter — first native-import engine consumer ([0f387ab](https://github.com/kontourai/flow-agents/commit/0f387ab8e5a8b7f65e511af2fc33340f51e2d047))
+* weekly runtime/SDK compatibility canary + dependabot ([9a371b1](https://github.com/kontourai/flow-agents/commit/9a371b1af86394fe1f7febebe3a35d3f05321f8e))
+
+
+### Fixes
+
+* opencode.json — emit schema-valid config (instructions must be array) ([35a01ec](https://github.com/kontourai/flow-agents/commit/35a01ec508b2f99d4a7bca854e5f09740bac4fb3))
+* opencode/pi hook chain — node resolution, stdin payloads, telemetry escape ([be4e4f8](https://github.com/kontourai/flow-agents/commit/be4e4f8d3b81fc7b67d6e45f4c9c1515407268a7))
+* pi extension template escaping; parse-gate generated hook artifacts ([6fe40c5](https://github.com/kontourai/flow-agents/commit/6fe40c5079b8ee89a58c4dfecd6df2992c46cf59))
+
+
+### Documentation
+
+* roadmap rows reflect the shipped utterance evidence-check hook ([#24](https://github.com/kontourai/flow-agents/issues/24)) ([617c755](https://github.com/kontourai/flow-agents/commit/617c75567b692c02564f457577d1ab3c01c1ea8e))
+
+## 0.1.2
+
+- Source validation resolves the Flow CLI at `dist/cli.js` (with a
+  `src/cli.js` fallback), and the source-and-static CI lane installs
+  `@kontourai/flow` so kit Flow Definitions are validated by the real
+  Flow CLI.
+- The publish workflow builds the bundle explicitly before `npm publish`.
+- Docs routing between the System Guidebook and the Workflow Usage Guide;
+  duplicated development walkthrough removed.
+- README and Pages home advertise the npm install with the version badge;
+  pre-release caveats removed; Kontour family table links product pages
+  and gains a Survey row.
+- Fixes phantom skill references, a stale pack list, and path accuracy in
+  the docs.
+
 ## 0.1.1
 
 ### Documentation And Site

package/CONTRIBUTING.md

@@ -34,6 +34,10 @@ gem install --user-install jekyll -v 3.9.5 jekyll-optional-front-matter \
 Set `FLOW_CLI_ROOT` to a Flow checkout or installed `@kontourai/flow` package
 root to enable full Flow Definition validation in `npm run validate:source`.
 
+## Releases
+
+Releases are automated with release-please: merges to main accumulate into a release PR, and merging it tags the version and dispatches the npm publish workflow. Use conventional commit prefixes (feat:, fix:, docs:, chore:) so version inference works.
+
 ## Validation
 
 - `npm run validate:source` — source-tree integrity (paths, packs, manifests)

package/README.md

@@ -2,53 +2,78 @@
 
 # Kontour Flow Agents
 
-**The discipline of Kontour Flow, inside the agent tools you already use.**
+**A portable process-discipline layer for agentic work — canonical policies, evidence, and telemetry that compile to whatever hook surface a host exposes.**
 
+[![npm version](https://img.shields.io/npm/v/%40kontourai%2Fflow-agents)](https://www.npmjs.com/package/@kontourai/flow-agents)
 [![CI](https://github.com/kontourai/flow-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/kontourai/flow-agents/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![Node >= 22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](package.json)
 
-[Documentation](https://kontourai.github.io/flow-agents/) · [Workflow Guide](docs/workflow-usage-guide.md) · [System Guidebook](docs/agent-system-guidebook.md) · [Kontour Flow](https://kontourai.github.io/flow/)
+[Documentation](https://kontourai.github.io/flow-agents/) · [Workflow Guide](docs/workflow-usage-guide.md) · [System Guidebook](docs/agent-system-guidebook.md) · [Runtime Hook Spec](docs/spec/runtime-hook-surface.md) · [Kontour Flow](https://kontourai.github.io/flow/)
 
 </div>
 
 ---
 
-Coding agents are powerful and forgetful. They plan well, then drift. They skip verification when context gets crowded. They call partial work done, and after a compaction nobody — including the agent — can say where the work actually stands.
+Agents are powerful and forgetful. They plan well, then drift. They skip verification when context gets crowded. They call partial work done, and after a compaction nobody — including the agent — can say where the work actually stands.
 
-Flow Agents wraps Codex, Claude Code, Kiro, and CI agents in an operating layer that makes long-running work inspectable: workflow skills that route requests into the right procedure, durable sidecar state that survives compaction and handoff, hooks that catch stop-short behavior, evidence gates before release decisions, and learning loops that feed corrections back into the system. [Kontour Flow](https://kontourai.github.io/flow/) owns the gate semantics underneath; Flow Agents makes that enforcement native inside agent harnesses.
+Flow Agents addresses this with a process-discipline layer that sits between the user and the agent: four canonical policy classes (workflow steering, quality gate, stop-goal-fit, config protection), durable sidecar state that survives compaction and handoff, evidence gates before release decisions, and telemetry that feeds corrections back into the system. [Kontour Flow](https://kontourai.github.io/flow/) owns the gate semantics underneath; Flow Agents compiles those policies to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next.
 
 **You ask for outcomes. The system supplies the path, the state, the checks, and the proof.**
 
 ## What you get
 
-- **One workflow across runtimes** — the same `idea → backlog → plan → build → review → verify → evidence → release → learning` path installs into Codex, Claude Code, and Kiro without rewriting it per tool.
+- **One workflow across runtimes** — the same `idea → backlog → plan → build → review → verify → evidence → release → learning` path installs into Claude Code, Codex, Kiro, opencode, and pi without rewriting it per tool.
 - **Workflow skills** — `idea-to-backlog`, `pull-work`, `plan-work`, `execute-plan`, `review-work`, `verify-work`, `evidence-gate`, `release-readiness`, `learning-review`, and orchestrators like `deliver` and `fix-bug` that chain them.
 - **Durable workflow state** — schema-validated sidecars under `.flow-agents/` record acceptance criteria, evidence, critique, handoff, and learning, so any session can resume from recorded state instead of chat memory.
-- **Stop-short protection** — runtime hooks check sidecar state and route the agent back when required evidence is missing, instead of letting it summarize past the gap.
+- **Four canonical policies** — workflow steering (phase reminders at each turn), quality gate (per-file checks after edits), stop-goal-fit (evidence check before the agent stops), and config protection (veto writes to linter/formatter configs). Each policy class has a canonical script under `scripts/hooks/` and compiles to the host's native hook format.
 - **Evidence over confidence** — important work ends with tests, browser checks, CI results, review findings, governance reports, or an explicit `NOT_VERIFIED` gap. Optional [Veritas](docs/veritas-integration.md) integration attaches repo-governance evidence without making it mandatory.
-- **Evals that keep the bundle honest** — static, integration, and behavioral eval lanes validate the skills, contracts, fixtures, and hook influence as the bundle evolves.
+- **Evals that keep the bundle honest** — 77 integration and 36 static bundle assertions validate the skills, contracts, fixtures, and hook influence as the bundle evolves.
+
+## Flow Agents as a process-discipline layer
+
+The four canonical policy classes are defined in the [Runtime Hook Surface spec](docs/spec/runtime-hook-surface.md) using a runtime-neutral vocabulary. Adapters translate them to whatever hook surface a host exposes:
+
+| Policy Class | What it does | Hook trigger |
+| --- | --- | --- |
+| Workflow steering | Injects phase-transition reminders so the agent does not lose track of where it is in the delivery pipeline | `userPromptSubmit` |
+| Quality gate | Runs format and lint checks immediately after edit tool calls | `postToolUse` |
+| Stop-goal-fit | Warns (or blocks) when the agent is about to stop but required evidence is missing | `stop` |
+| Config protection | Vetoes writes to linter and formatter configuration files | `preToolUse` |
+
+The spec defines three conformance levels: **L0** (telemetry only), **L1** (steering + stop-goal-fit warning), and **L2** (all four policies with blocking). Claude Code and Codex are the current L2 reference implementations.
+
+## Runtime and support matrix
+
+| Tier | Runtime | Ships | Tested | Conformance |
+| --- | --- | --- | --- | --- |
+| **Core harness** | Claude Code | install + hooks + bundle | 77 integration + 36 static assertions | L2 — reference implementation |
+| **Core harness** | Codex | install + hooks + bundle | 77 integration + 36 static assertions | L2 — reference implementation |
+| **Core harness** | Kiro | install + hooks + bundle | included in bundle assertions | L2 |
+| **Core harness** | opencode | `.opencode/agents/`, `.opencode/skills/`, `.opencode/plugins/flow-agents.js`, `opencode.json` | included in bundle assertions | L1 — no prompt-submit hook; steering wired to `session.created` + `tool.execute.before` |
+| **Core harness** | pi | `.pi/extensions/flow-agents.ts`, `.pi/skills/`, `AGENTS.md` | included in bundle assertions | L1 — no stop hook; stop-goal-fit unavailable |
+| **Official framework adapter** | AWS Strands (Python) | `integrations/strands/` — `flow-agents-strands` PyPI package | 50 unit tests (no Strands SDK required) | Spike/preview — see [integrations/strands/README.md](integrations/strands/README.md) |
+| **Conformance-certified** | Community / third-party | Self-certify using the conformance kit | — | Conformance kit in development; not yet shipped |
+
+Honest gaps are documented in the artifacts: opencode has no native `prompt.submit`-equivalent event; Codex live hook influence is limited to installed-command and protocol coverage; pi has no `permissionRequest` equivalent and no stop hook. The [Runtime Hook Surface spec](docs/spec/runtime-hook-surface.md) names every gap explicitly.
 
 ## Install
 
 ```bash
-# guided install into your workspace
+# guided install into your workspace (auto-detects runtime)
 npx @kontourai/flow-agents init --dest /path/to/workspace
 
 # headless, for CI or scripts
 npx @kontourai/flow-agents init --dest /path/to/workspace --telemetry-sink local-files --yes
 
-# with runtime-specific wiring and kit activation
+# runtime-specific wiring
+npx @kontourai/flow-agents init --runtime claude-code --dest /path/to/workspace --yes
 npx @kontourai/flow-agents init --runtime codex --dest /path/to/workspace --activate-kits --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
 ```
 
-Until the first npm release lands, the same commands work from a checkout:
-
-```bash
-git clone https://github.com/kontourai/flow-agents.git
-cd flow-agents && npm install && npm run build
-node build/src/cli.js init --dest /path/to/workspace
-```
+Working from a checkout (for contributors): `npm install && npm run build`, then `node build/src/cli.js init --dest /path/to/workspace`.
 
 The installer copies the bundled agents, skills, context, scripts, evals, Flow Kit assets, and the Flow Agents-owned `console.telemetry.json` descriptor into the target workspace. Telemetry writes to local files by default; optional sinks mirror it to a local, hosted, or self-hosted Kontour Console (`--telemetry-sink local-kontour-console | kontour-hosted-console | user-hosted-console --console-url …`).
 
@@ -80,15 +105,29 @@ Use fix-bug. Reproduce the issue, diagnose root cause, plan the fix, implement i
 
 The [Workflow Usage Guide](docs/workflow-usage-guide.md) walks every stage with example prompts and expected behavior; the [Agent System Guidebook](docs/agent-system-guidebook.md) is the plain-language map of how the pieces fit.
 
+## Framework adapters
+
+The same canonical policies that wire into coding-agent harnesses via file-based hook scripts can also wire into agent frameworks as in-process language-native packages.
+
+`integrations/strands/` contains `flow-agents-strands`, a Python package implementing a Strands `HookProvider` that:
+- emits the canonical telemetry taxonomy (`agentSpawn`, `preToolUse`, `postToolUse`, `stop`, etc.) to the same JSONL format as the harness adapters
+- enforces config protection via `BeforeToolCallEvent` cancellation (the Strands equivalent of a blocking `preToolUse` hook)
+- injects workflow steering context at agent construction via `steering_context()`
+
+This is a spike/preview — 50 unit tests pass without requiring the Strands SDK, and the README documents 7 limitations honestly. It demonstrates that the policy engine is not harness-specific.
+
+The [Runtime Hook Surface spec](docs/spec/runtime-hook-surface.md) documents the full framework adapter mapping, including VoltAgent, LangGraph, and OpenAI Agents SDK hook surfaces, and the minimum viable adapter pseudocode.
+
 ## Where Flow Agents fits
 
 Kontour AI shows the work behind AI. Each product stands alone; together they cohere:
 
 | Product | Owns |
 | --- | --- |
-| **[Surface](https://github.com/kontourai/surface)** | Portable trust state: claims, evidence, policies, trust snapshots |
-| **[Flow](https://github.com/kontourai/flow)** | Process transparency: steps, gates, transitions, runs, exceptions, reports |
-| **[Veritas](https://github.com/kontourai/veritas)** | Code/change transparency: repo standards, merge readiness |
+| **[Survey](https://kontourai.io/survey)** | Producer evidence: source → extraction → candidate → review → claim |
+| **[Surface](https://kontourai.io/surface)** | Portable trust state: claims, evidence, policies, trust snapshots |
+| **[Flow](https://kontourai.io/flow)** | Process transparency: steps, gates, transitions, runs, exceptions, reports |
+| **[Veritas](https://kontourai.io/veritas)** | Code/change transparency: repo standards, merge readiness |
 | **Flow Agents** | Agent-facing distribution: skills, kits, runtime adapters, hooks, telemetry |
 
 Flow Agents owns the glue — discovery, just-in-time guidance, scoped delegation, Flow-backed state inside harnesses, evidence-backed completion, and feedback loops. It deliberately does not own the model, the runtime, the workflow engine, or repo governance. The [North Star](docs/north-star.md) records the direction and design principles.

package/build/src/cli/init.js

@@ -13,12 +13,67 @@ const runtimeBundles = {
     codex: "codex",
     "claude-code": "claude-code",
     kiro: "kiro",
+    opencode: "opencode",
+    pi: "pi",
 };
+// Stable marker present in every Flow Agents claude-code hook command.
+// Used by scope-collision detection to identify an existing flow-agents install.
+// Marker must be distinctive to Flow Agents generated settings. Sibling
+// products from the same lineage ship identically named hook scripts such
+// as claude-hook-adapter.js, so script filenames are NOT a safe marker.
+export const COLLISION_MARKER = "Recording Flow Agents telemetry";
+/**
+ * Check whether a user-level Claude Code settings file already contains
+ * Flow Agents hook commands. If it does, print a WARNING explaining that
+ * Claude Code merges user-level and project-level settings and runs ALL
+ * matching hooks, so having flow-agents in both places causes duplicate
+ * hook execution (double telemetry, double policy enforcement).
+ *
+ * The check does NOT block the install; it is advisory only.
+ *
+ * @param userSettingsFile Path to inspect (defaults to $HOME/.claude/settings.json;
+ *   overridable via FLOW_AGENTS_USER_CLAUDE_SETTINGS env var for testability).
+ * @returns true if a collision was detected, false otherwise.
+ */
+export function checkScopeCollision(userSettingsFile) {
+    const filePath = userSettingsFile
+        ?? process.env["FLOW_AGENTS_USER_CLAUDE_SETTINGS"]
+        ?? path.join(os.homedir(), ".claude", "settings.json");
+    if (!fs.existsSync(filePath))
+        return false;
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    if (!text.includes(COLLISION_MARKER))
+        return false;
+    console.warn(`\nWARNING: Flow Agents scope collision detected.\n` +
+        `  ${filePath}\n` +
+        `already contains Flow Agents hook commands (marker: ${COLLISION_MARKER}).\n` +
+        `\n` +
+        `Claude Code merges user-level (~/.claude/settings.json) and project-level\n` +
+        `(.claude/settings.json) settings, then runs ALL matching hooks from both files.\n` +
+        `Installing Flow Agents at the project level while it is also present at the\n` +
+        `user level will cause duplicate hook execution: telemetry events are recorded\n` +
+        `twice and policy hooks (workflow-steering, config-protection, quality-gate,\n` +
+        `stop-goal-fit) run twice per event.\n` +
+        `\n` +
+        `To resolve:\n` +
+        `  - Remove the hooks section from ${filePath} and rely solely on the\n` +
+        `    project-level .claude/settings.json installed by flow-agents init, OR\n` +
+        `  - Remove the project-level install and keep only the user-level one.\n` +
+        `\n` +
+        `The install will continue; resolve the collision before running Claude Code.\n`);
+    return true;
+}
 function usage() {
     console.error(`usage: flow-agents init [options]
 
 Options:
-  --runtime base|codex|claude-code|kiro
+  --runtime base|codex|claude-code|kiro|opencode|pi
   --dest PATH
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
@@ -35,9 +90,9 @@ function normalizeRuntime(value) {
         return undefined;
     if (value === "claude")
         return "claude-code";
-    if (value === "base" || value === "codex" || value === "claude-code" || value === "kiro")
+    if (value === "base" || value === "codex" || value === "claude-code" || value === "kiro" || value === "opencode" || value === "pi")
         return value;
-    throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, or kiro`);
+    throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, kiro, opencode, or pi`);
 }
 function normalizeTelemetrySink(value) {
     if (value === "local-files" || value === "local-kontour-console" || value === "kontour-hosted-console" || value === "user-hosted-console" || value === "kontour-cloud" || value === "hosted-kontour-console")
@@ -67,7 +122,7 @@ async function questionHidden(prompt) {
         let value = "";
         const onData = (buffer) => {
             const text = buffer.toString("utf8");
-            if (text === "\u0003") {
+            if (text === "") {
                 stdout.write("\n");
                 process.exit(130);
             }
@@ -78,7 +133,7 @@ async function questionHidden(prompt) {
                 resolve(value);
                 return;
             }
-            if (text === "\u007f") {
+            if (text === "") {
                 value = value.slice(0, -1);
                 return;
             }
@@ -224,6 +279,18 @@ export async function main(argv = process.argv.slice(2)) {
     const headless = argv.includes("--yes") || argv.includes("--headless") || !process.stdin.isTTY;
     try {
         const options = headless ? headlessOptions(argv) : await interactiveOptions(argv);
+        // Scope-collision check for claude-code: Claude Code merges user-level
+        // (~/.claude/settings.json) and project-level (.claude/settings.json) settings
+        // and runs ALL matching hooks from both files. If a user-level settings file
+        // already contains flow-agents hooks, installing at the project level will
+        // cause duplicate hook execution. We warn but do not block.
+        //
+        // Codex note: Codex hooks live in .codex/hooks.json (project-level only).
+        // There is no well-known user-level codex hooks file in our install paths,
+        // so no collision check is needed for codex.
+        if (options.runtime === "claude-code") {
+            checkScopeCollision();
+        }
         const bundle = ensureBundle(options.runtime);
         const installed = installBundle(bundle, options);
         if (installed !== 0)
@@ -235,5 +302,148 @@ export async function main(argv = process.argv.slice(2)) {
         return 2;
     }
 }
+// ---------------------------------------------------------------------------
+// Dogfood subcommand
+//
+// `flow-agents dogfood --runtime claude-code [--dest PATH]`
+//
+// Writes only the hook-wiring artifacts for the specified runtime into the
+// target directory (default: cwd). Unlike a full install, dogfood:
+//   - Does NOT rsync the full bundle (no agents/skills duplication).
+//   - Reads the generated settings/config from dist/<runtime>/ so the output
+//     cannot drift from what the bundle generates (DRY guarantee).
+//   - For claude-code: OMITS permissions.defaultMode and
+//     skipDangerousModePermissionPrompt (permissive defaults are for installed
+//     workspaces, not source repos).
+//   - Runs the same scope-collision warning as init.
+// ---------------------------------------------------------------------------
+function dogfoodUsage() {
+    console.error(`usage: flow-agents dogfood [options]
+
+Options:
+  --runtime claude-code|codex|opencode|pi   (required)
+  --dest PATH                               (default: cwd)
+  --yes, --headless
+`);
+}
+function normalizeDogfoodRuntime(value) {
+    if (!value)
+        return undefined;
+    if (value === "claude" || value === "claude-code")
+        return "claude-code";
+    if (value === "codex" || value === "opencode" || value === "pi")
+        return value;
+    throw new Error(`dogfood: unsupported runtime '${value}'; expected claude-code, codex, opencode, or pi`);
+}
+/**
+ * Write the claude-code hook-wiring artifacts into dest.
+ * Reads dist/claude-code/.claude/settings.json (generated by build-bundles),
+ * strips the permissive-mode permission keys (defaultMode, skipDangerousModePermissionPrompt),
+ * and writes .claude/settings.json to dest.
+ */
+function dogfoodClaudeCode(bundleRoot, dest) {
+    const sourcePath = path.join(bundleRoot, ".claude", "settings.json");
+    if (!fs.existsSync(sourcePath))
+        throw new Error(`dogfood: bundle settings missing: ${sourcePath}`);
+    const settings = JSON.parse(fs.readFileSync(sourcePath, "utf8"));
+    // Remove permissive defaults that are only appropriate for installed workspaces.
+    // These keys must not be present in the source repo's .claude/settings.json.
+    delete settings["permissions"];
+    delete settings["skipDangerousModePermissionPrompt"];
+    const outDir = path.join(dest, ".claude");
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(path.join(outDir, "settings.json"), `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+/**
+ * Write the codex hook-wiring artifacts into dest.
+ * Reads dist/codex/.codex/hooks.json and writes .codex/hooks.json to dest.
+ * The monolithic .codex/config.toml is not written here because it contains
+ * workspace settings (approvals_reviewer, features) that would override the
+ * developer's existing codex configuration. Only the hooks file is written.
+ */
+function dogfoodCodex(bundleRoot, dest) {
+    const sourcePath = path.join(bundleRoot, ".codex", "hooks.json");
+    if (!fs.existsSync(sourcePath))
+        throw new Error(`dogfood: bundle hooks.json missing: ${sourcePath}`);
+    const hooks = fs.readFileSync(sourcePath, "utf8");
+    const outDir = path.join(dest, ".codex");
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(path.join(outDir, "hooks.json"), hooks, "utf8");
+}
+/**
+ * Write the opencode hook-wiring artifacts into dest.
+ * Reads dist/opencode/.opencode/plugins/flow-agents.js and opencode.json,
+ * and writes them into dest. These are the minimal hook-wiring files; the
+ * full skill/agent tree is not copied.
+ */
+function dogfoodOpencode(bundleRoot, dest) {
+    const pluginSource = path.join(bundleRoot, ".opencode", "plugins", "flow-agents.js");
+    const configSource = path.join(bundleRoot, "opencode.json");
+    if (!fs.existsSync(pluginSource))
+        throw new Error(`dogfood: bundle plugin missing: ${pluginSource}`);
+    const pluginDir = path.join(dest, ".opencode", "plugins");
+    fs.mkdirSync(pluginDir, { recursive: true });
+    fs.copyFileSync(pluginSource, path.join(pluginDir, "flow-agents.js"));
+    // Write opencode.json only if it does not already exist to avoid clobbering
+    // any workspace-specific opencode configuration.
+    const destConfig = path.join(dest, "opencode.json");
+    if (!fs.existsSync(destConfig) && fs.existsSync(configSource)) {
+        fs.copyFileSync(configSource, destConfig);
+    }
+}
+/**
+ * Write the pi hook-wiring artifacts into dest.
+ * Reads dist/pi/.pi/extensions/flow-agents.ts and writes it to dest.
+ * The extension is the only hook-wiring file needed for pi.
+ */
+function dogfoodPi(bundleRoot, dest) {
+    const extSource = path.join(bundleRoot, ".pi", "extensions", "flow-agents.ts");
+    if (!fs.existsSync(extSource))
+        throw new Error(`dogfood: bundle extension missing: ${extSource}`);
+    const extDir = path.join(dest, ".pi", "extensions");
+    fs.mkdirSync(extDir, { recursive: true });
+    fs.copyFileSync(extSource, path.join(extDir, "flow-agents.ts"));
+}
+export async function mainDogfood(argv = process.argv.slice(2)) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        dogfoodUsage();
+        return 0;
+    }
+    const args = parseArgs(argv);
+    try {
+        const runtimeRaw = flagString(args.flags, "runtime");
+        const runtime = normalizeDogfoodRuntime(runtimeRaw);
+        if (!runtime) {
+            console.error("dogfood: --runtime is required (claude-code, codex, opencode, or pi)");
+            dogfoodUsage();
+            return 2;
+        }
+        const dest = path.resolve(flagString(args.flags, "dest") ?? process.cwd());
+        // Ensure the bundle for the requested runtime is built.
+        const bundleRuntime = runtime;
+        const bundleRoot = ensureBundle(bundleRuntime);
+        // Scope-collision check: warn if user-level claude settings already has flow-agents.
+        // Codex: no user-level hooks file in our install paths — skip with note above.
+        if (runtime === "claude-code") {
+            checkScopeCollision();
+        }
+        // Write only the hook-wiring artifacts, not the full bundle.
+        fs.mkdirSync(dest, { recursive: true });
+        if (runtime === "claude-code")
+            dogfoodClaudeCode(bundleRoot, dest);
+        else if (runtime === "codex")
+            dogfoodCodex(bundleRoot, dest);
+        else if (runtime === "opencode")
+            dogfoodOpencode(bundleRoot, dest);
+        else if (runtime === "pi")
+            dogfoodPi(bundleRoot, dest);
+        console.log(`Flow Agents dogfood hooks wired for ${runtime} in ${dest}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(`flow-agents dogfood: ${error.message}`);
+        return 2;
+    }
+}
 if (import.meta.url === `file://${process.argv[1]}`)
     process.exit(await main());