@haposoft/cafekit 0.8.17 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.17",
+  "version": "0.9.1",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
@@ -43,5 +43,8 @@
   ],
   "engines": {
     "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.15.11"
   }
 }

package/src/claude/CLAUDE.md

@@ -15,7 +15,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - Do not assume silently. State assumptions when they affect the work.
 - If multiple interpretations are plausible, surface them before implementation.
 - If the simpler option is likely better, say so and push back.
-- If the task/spec is too vague to verify, stop and ask or route back to spec correction.
+- If the user asks a question about the project, use `/hapo:question` to answer from source evidence before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -46,7 +46,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 Use this loop for non-trivial work:
 
 1. **Understand** — read README, relevant docs, active spec/task, and existing code.
-2. **Plan** — choose the smallest coherent path; use `/hapo:specs` for feature specs when needed.
+2. **Plan** — choose the smallest coherent path; use `/hapo:question` for evidence-backed project questions and `/hapo:specs` for feature specs when ready.
 3. **Execute** — implement only the active task/scope; no placeholder completion.
 4. **Verify** — run exact task commands first, then repo-level lint/test/build as needed.
 5. **Sync** — mark task state only after proof exists.

package/src/claude/migration-manifest.json

@@ -27,6 +27,7 @@
       "mobile-development",
       "pdf",
       "pptx",
+      "question",
       "react-best-practices",
       "research",
       "specs",

package/src/claude/rules/skill-domain-routing.md

@@ -29,6 +29,7 @@ User wants to...
 
 ```text
 User wants to...
+├── answer questions from source code/docs/specs/config    -> /hapo:question
 ├── find files, locate code, scan project structure       -> /hapo:inspect
 ├── diagnose an error or failing check                    -> /hapo:debug
 ├── understand possible side effects                      -> /hapo:impact-analysis
@@ -41,6 +42,7 @@ Local source truth comes from `/hapo:inspect`; external/current knowledge comes
 
 ```text
 User wants to...
+├── ask/answer documentation questions from source         -> /hapo:question
 ├── create missing project docs                           -> /hapo:docs --init
 ├── update docs after source changes                      -> /hapo:docs --update
 ├── summarize codebase quickly                            -> /hapo:docs --summarize

package/src/claude/rules/skill-workflow-routing.md

@@ -7,11 +7,13 @@ Do not inject or force a skill when the user explicitly asks for a direct answer
 ## Core Specification Workflow
 
 ```text
-/hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
+/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
 | User intent | Suggested start |
 |---|---|
+| ask about source code, docs, specs, config, dependencies, or external/current technical facts | `/hapo:question` |
+| vague request, missing acceptance criteria, unclear scope, stakeholder questions | ask one clarification or use `/hapo:brainstorm` |
 | unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
 | create requirements, design, task breakdown, validate spec | `/hapo:specs` |
 | implement an approved spec or a specific task file | `/hapo:develop` |
@@ -81,4 +83,6 @@ Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local sourc
 - Add a secondary skill only when it materially changes execution.
 - Prefer explicit user commands over this table.
 - If two workflows conflict, ask one concise clarification.
+- If the user asks a factual or project question before workflow selection, use `/hapo:question`.
+- If missing information blocks workflow selection, ask one concise clarification or use `/hapo:brainstorm`.
 - If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.

package/src/claude/skills/question/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: hapo:question
+description: "Answer questions with evidence. Use when the user asks about project behavior, source code, specs, docs, configuration, dependencies, or external technical information; inspect the repo first, use internet/current docs when repo evidence is insufficient, and ask back only when the question cannot be answered safely."
+argument-hint: "<question> [--repo|--web|--both|--brief|--deep]"
+version: 1.0.0
+---
+
+# Question Skill
+
+`hapo:question` is an evidence-backed question-answering skill. It answers user questions by checking the local project first, then external/current sources when the repository cannot answer the question.
+
+## Core Stance
+
+- Answer the question; do not turn every question into a spec or planning session.
+- Source-first: prefer README, docs, specs, code, config, tests, logs, and package metadata before assumptions.
+- Use external/current sources when the local repo is missing the answer, the topic is version-sensitive, or the user asks about outside tools, libraries, APIs, laws, pricing, or best practices.
+- Ask back only when the question is too broad, has no target, needs credentials/private context, or any answer would be misleading.
+- Do not edit files, implement code, create specs, or change project state.
+
+<ANSWER-ONLY-GATE>
+Do NOT implement, scaffold, refactor, modify files, generate full specs, or make final architecture decisions.
+The output is an answer, evidence, confidence, and a follow-up only when needed.
+</ANSWER-ONLY-GATE>
+
+## When To Use
+
+Use `hapo:question` when the user asks:
+- "Trong hệ thống này X làm gì?"
+- "Luồng này đang xử lý ở đâu?"
+- "Config/version/package hiện tại là gì?"
+- "Có dùng thư viện/công nghệ/cách làm nào không?"
+- "Requirement/spec này có khớp code không?"
+- "Tool/library/framework này nên dùng thế nào?"
+- "Theo best practice/current docs thì sao?"
+- "Tôi nên hiểu phần này như thế nào?"
+
+Do not use it when:
+- The user asks to implement, fix, debug, test, commit, or publish.
+- The user wants ideation/tradeoff exploration; use `hapo:brainstorm`.
+- The user wants a formal spec; use `hapo:specs`.
+- The user wants full legacy documentation reconstruction; use `hapo:docs --reconstruct`.
+- The user wants root-cause diagnosis for a failure; use `hapo:debug`.
+
+## Modes
+
+- Default: repo-first answer. Use external sources only if local evidence is insufficient.
+- `--repo`: answer from local source only. If not enough evidence, say so and do not use web.
+- `--web`: answer from external/current sources. Still read local context if the question mentions this project.
+- `--both`: explicitly combine local source evidence and external/current evidence.
+- `--brief`: short answer, minimal evidence.
+- `--deep`: broader evidence scan, include trace and tradeoffs.
+
+If modes conflict, prefer the most explicit source mode in this order: `--both`, `--repo`, `--web`, then default. Apply `--brief` or `--deep` as output depth modifiers.
+
+## Workflow
+
+### 1. Classify The Question
+
+Pick one primary answer type:
+
+```text
+source-code behavior | config/version | spec/docs consistency | dependency/library | workflow/process | external/current knowledge | unclear
+```
+
+If `unclear`, ask one focused follow-up with the minimum choices needed.
+
+### 2. Gather Evidence
+
+Repo evidence priority:
+1. `README.md`, `AGENTS.md`, `CLAUDE.md`
+2. relevant `docs/`, `specs/`, `.claude/`, `.opencode/`
+3. source files, tests, scripts, package manifests, config files
+4. git history only when the question asks about changes or provenance
+
+Use focused search (`rg`, targeted file reads) instead of broad scans. Use `hapo:inspect` when the user asks where something lives or the source surface is unclear.
+
+External evidence:
+- Use external/current docs when repo evidence is absent, stale, or not authoritative.
+- Prefer official docs, standards, source repositories, or primary vendor docs.
+- State clearly when an answer is inferred from external docs rather than confirmed in the repo.
+
+### 3. Decide Whether To Answer Or Ask Back
+
+Answer directly when at least one of these is true:
+- repo evidence answers the question,
+- external/current evidence answers the non-project part,
+- a cautious answer can separate known facts from inference.
+
+Ask back when:
+- the target system/module is not named and multiple targets are plausible,
+- the needed file/source is blocked or private,
+- the question requires business/domain judgment not present in source,
+- the answer would require guessing customer intent,
+- the question bundles multiple unrelated topics.
+
+Ask only one follow-up question. Include 2-3 concrete options if helpful.
+
+### 4. Output Contract
+
+Default output:
+
+```markdown
+**Answer**
+...
+
+**Evidence**
+- `path/to/file`: what it proves
+- External: source name/link, what it proves
+
+**Confidence**
+high | medium | low
+
+**Gaps**
+- ...
+
+**Next**
+...
+```
+
+Use `templates/question.md` when the user asks to save or document the answer.
+
+## Answer Style
+
+- Lead with the answer, not the research process.
+- Use file paths and line references when local evidence is used.
+- Separate "confirmed by source" from "inferred".
+- Keep the answer proportional: concise for simple questions, structured for complex ones.
+- If external sources were used, include source links or names.
+- If no evidence exists, say "không thấy bằng chứng trong source hiện tại" and explain what was checked.
+
+## Examples
+
+### Source Question
+
+```text
+/hapo:question "Trong hệ thống này cafekit dùng file nào để bật/tắt skill routing?"
+```
+
+Expected behavior:
+- read runtime/config/install files,
+- answer with exact config file and relevant keys,
+- say whether it is runtime-driven or hard-coded.
+
+### Mixed Source + Web Question
+
+```text
+/hapo:question "Dự án này đang dùng React version nào, và version đó có còn phù hợp theo best practice hiện tại không?" --both
+```
+
+Expected behavior:
+- read `package.json` or lockfile,
+- check current React docs/release info if needed,
+- separate local version from external recommendation.
+
+### Ask Back
+
+```text
+/hapo:question "Hệ thống này có ổn không?"
+```
+
+Expected behavior:
+- ask one narrowing question because "ổn" could mean architecture, security, performance, UX, tests, or deploy readiness.

package/src/claude/skills/question/templates/question.md

@@ -0,0 +1,32 @@
+# Question Answer: {{TITLE}}
+
+## Question
+{{QUESTION}}
+
+## Answer
+{{ANSWER}}
+
+## Evidence
+| Source | Finding | Confidence |
+|---|---|---|
+| {{SOURCE}} | {{FINDING}} | {{CONFIDENCE}} |
+
+## Source Trace
+- Repo files checked: {{REPO_FILES}}
+- External/current sources checked: {{EXTERNAL_SOURCES}}
+- Search terms or commands: {{SEARCH_TRACE}}
+
+## Confirmed Facts
+- {{FACT}}
+
+## Inferences
+- {{INFERENCE}}
+
+## Gaps / Unknowns
+- {{GAP}}
+
+## Follow-up Question
+{{FOLLOW_UP_OR_NONE}}
+
+## Next
+{{NEXT_STEP}}

package/src/opencode/AGENTS.md

@@ -7,8 +7,8 @@ Primary operating instructions for OpenCode using the CafeKit runtime.
 - Project instructions live in `AGENTS.md`.
 - CafeKit commands live in `.opencode/commands/` and use OpenCode-native slash names without the `hapo:` prefix.
 - CafeKit subagents live in `.opencode/agents/` using OpenCode frontmatter.
-- CafeKit skills intentionally live in `.claude/skills/` because OpenCode reads Claude-compatible skills natively.
-- Shared CafeKit support files live in `.claude/rules/`, `.claude/scripts/`, `.claude/references/`, and `.claude/runtime.json`.
+- CafeKit skills live in `.opencode/skills/` and are read natively by OpenCode.
+- Shared CafeKit support files live in `.opencode/rules/`, `.opencode/scripts/`, `.opencode/references/`, and `.opencode/runtime.json`.
 - OpenCode config is merged into `opencode.json`; keep project-specific model/provider choices there.
 
 ## Command Surface
@@ -16,6 +16,7 @@ Primary operating instructions for OpenCode using the CafeKit runtime.
 Use these OpenCode commands:
 
 - `/brainstorm <idea-or-problem>`: scout and narrow an unclear idea before specs.
+- `/question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when needed.
 - `/specs <feature-or-spec-command>`: create, update, validate, or approve specs.
 - `/develop <feature> [task-file] [--flash]`: implement approved spec tasks.
 - `/test [scope|--full]`: verify implementation and collect evidence.
@@ -26,7 +27,7 @@ Use these OpenCode commands:
 - `/inspect <target>`: inspect source, artifacts, or external context.
 - `/generate-graph <request>`: generate technical diagrams.
 
-The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.claude/skills/<skill>/SKILL.md`.
+The underlying CafeKit skills are still named `hapo:*` in their documentation. In OpenCode, use the commands above; each command reads the matching skill from `.opencode/skills/<skill>/SKILL.md`.
 
 ## Core Objective
 
@@ -41,7 +42,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 - Do not assume silently. State assumptions when they affect the work.
 - If multiple interpretations are plausible, surface them before implementation.
 - If the simpler option is likely better, say so and push back.
-- If the task/spec is too vague to verify, stop and ask or route back to spec correction.
+- If the user asks a question about the project, use `/question` to answer from source evidence before planning.
 - Before feature planning or coding, read `./README.md` for project context.
 
 ### 2. Simplicity First
@@ -72,7 +73,7 @@ These rules reduce common agent coding failures: hidden assumptions, overbuilt s
 Use this loop for non-trivial work:
 
 1. Understand: read README, relevant docs, active spec/task, and existing code.
-2. Plan: choose the smallest coherent path; use `/specs` for feature specs when needed.
+2. Plan: choose the smallest coherent path; use `/question` for evidence-backed project questions and `/specs` for feature specs when ready.
 3. Execute: implement only the active task/scope; no placeholder completion.
 4. Verify: run exact task commands first, then repo-level lint/test/build as needed.
 5. Sync: mark task state only after proof exists.
@@ -137,4 +138,3 @@ Consult these when the task touches the relevant area:
 ## Language Consistency
 
 When generating specs or structured project output, use the user's preferred language consistently across the whole spec workspace. Technical terms, code samples, and file paths may remain English.
-

package/src/opencode/plugins/docs-sync.ts

@@ -0,0 +1,181 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — docs-sync.ts
+ *
+ * Port of .claude/hooks/docs-sync.cjs.
+ *
+ * Behavior:
+ * - On session.created: detect if project has source code but no docs/, or if
+ *   docs/.sync_hash is stale relative to current source-only git hash.
+ * - Write banner to `.opencode/session-banner.md` so AGENTS.md / skills can
+ *   surface it (OpenCode event console.log does not flow into assistant
+ *   context, only the server log).
+ * - Also print to stderr so the OpenCode server log records it.
+ *
+ * Disable via `.opencode/runtime.json` { "docsSync": false }.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  appendFileSync,
+} from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const BANNER_SECTION_START = "<!-- CAFEKIT DOCS SYNC START -->";
+const BANNER_SECTION_END = "<!-- CAFEKIT DOCS SYNC END -->";
+
+function readRuntime(cwd: string): Record<string, any> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function resolveDocsDir(cwd: string, runtime: Record<string, any>): string {
+  const configured = runtime.paths?.docs;
+  return join(cwd, typeof configured === "string" && configured ? configured : "docs");
+}
+
+function hasSourceCode(cwd: string): boolean {
+  return (
+    existsSync(join(cwd, "src")) ||
+    existsSync(join(cwd, "app")) ||
+    existsSync(join(cwd, "lib")) ||
+    existsSync(join(cwd, "package.json")) ||
+    existsSync(join(cwd, "index.js")) ||
+    existsSync(join(cwd, "main.py"))
+  );
+}
+
+function currentSourceHash(cwd: string): string {
+  try {
+    return execSync('git log -1 --format="%H" -- . ":(exclude)docs"', {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+function buildMissingDocsBanner(): string {
+  return [
+    "### 🔴 URGENT SYSTEM ACTION: MISSING DOCUMENTATION 🔴",
+    "> BẮT BUỘC (MANDATORY): Hệ thống phát hiện dự án đã có Source Code nhưng thư mục `docs/` chưa tồn tại.",
+    "> Nhiệm vụ ĐẦU TIÊN của bạn trong session này là đọc hiểu mã nguồn hiện tại và tạo ra các tài liệu tiêu chuẩn:",
+    "> 1. `docs/system-architecture.md` (Kiến trúc hệ thống, phân tích flow)",
+    "> 2. `docs/project-overview-pdr.md` (Tổng quan, mục tiêu, tính năng)",
+    "> 3. Khởi tạo file hidden `docs/.sync_hash` để theo dõi cập nhật.",
+    "> ",
+    '> LƯU Ý BẮT BUỘC: Bạn phải chạy lệnh Git này trong Terminal để lấy Hash Code mới nhất: `git log -1 --format="%H" -- . ":(exclude)docs"`',
+    "> Sau đó ghi chuẩn giá trị Hash đó vào file `docs/.sync_hash`.",
+  ].join("\n");
+}
+
+function buildStaleDocsBanner(currentHash: string, lastSyncHash: string): string {
+  return [
+    "### 🔄 CONTINUOUS DOCS SYNC REQUIRED 🔄",
+    `> Source Code vừa có sự thay đổi mới (Git Hash: \`${currentHash}\`) kể từ lần đồng bộ Docs cuối cùng (\`${lastSyncHash || "Chưa gán"}\`).`,
+    "> YÊU CẦU TRƯỚC KHI LÀM THÊM TÍNH NĂNG:",
+    `> 1. Rà soát file bị thay đổi gần đây (dùng \`git diff ${lastSyncHash} ${currentHash}\` hoặc \`git log\`).`,
+    "> 2. Cập nhật lại `docs/system-architecture.md` hoặc các chuẩn code nếu cần thiết.",
+    "> 3. Cập nhật Changelog (nhật ký thay đổi).",
+    `> 4. KHI HOÀN TẤT, BẠN PHẢI GHI ĐÈ GIÁ TRỊ SAU: \`${currentHash}\` VÀO FILE \`docs/.sync_hash\` ĐỂ CHỐT TRẠNG THÁI HIỆN TẠI.`,
+  ].join("\n");
+}
+
+function writeBanner(cwd: string, banner: string | null): void {
+  const target = join(cwd, ".opencode", "session-banner.md");
+  const dir = dirname(target);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const existing = existsSync(target) ? readFileSync(target, "utf8") : "";
+  const pattern = new RegExp(`${BANNER_SECTION_START}[\\s\\S]*?${BANNER_SECTION_END}\\n?`);
+  const cleaned = existing.replace(pattern, "").trimEnd();
+
+  if (!banner) {
+    if (cleaned !== existing.trimEnd()) {
+      writeFileSync(target, cleaned ? `${cleaned}\n` : "");
+    }
+    return;
+  }
+
+  const block = [BANNER_SECTION_START, banner, BANNER_SECTION_END].join("\n");
+  const next = cleaned ? `${cleaned}\n\n${block}\n` : `${block}\n`;
+  writeFileSync(target, next);
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: "docs-sync",
+        status: "crash",
+        error: error instanceof Error ? error.message : String(error),
+      }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+export const DocsSync: Plugin = async ({ directory }) => ({
+  event: async ({ event }) => {
+    try {
+      if (event.type !== "session.created") return;
+
+      const cwd = directory;
+      const runtime = readRuntime(cwd);
+      if (runtime.docsSync === false) return;
+
+      if (!hasSourceCode(cwd)) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const docsDir = resolveDocsDir(cwd, runtime);
+
+      if (!existsSync(docsDir)) {
+        const banner = buildMissingDocsBanner();
+        writeBanner(cwd, banner);
+        console.error(banner);
+        return;
+      }
+
+      const currentHash = currentSourceHash(cwd);
+      if (!currentHash) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const syncFile = join(docsDir, ".sync_hash");
+      const lastSyncHash = existsSync(syncFile) ? readFileSync(syncFile, "utf8").trim() : "";
+
+      if (lastSyncHash === currentHash) {
+        writeBanner(cwd, null);
+        return;
+      }
+
+      const banner = buildStaleDocsBanner(currentHash, lastSyncHash);
+      writeBanner(cwd, banner);
+      console.error(banner);
+    } catch (error) {
+      logCrash(error);
+    }
+  },
+});

package/src/opencode/plugins/inspect-block.ts

@@ -0,0 +1,164 @@
+/**
+ * Copyright (c) 2026 Haposoft. MIT License.
+ *
+ * OpenCode Plugin — inspect-block.ts
+ *
+ * Port of .claude/hooks/inspect-block.cjs.
+ *
+ * Behavior:
+ * - Block reads/writes/globs/greps that target heavy directories (node_modules,
+ *   .git, dist, build, .next, .venv, vendor, target, coverage, ...).
+ * - Block excessively broad glob patterns (e.g. **\/* alone).
+ * - Allow approved build/package-manager bash commands.
+ *
+ * Disable via `.opencode/runtime.json` { "inspect": { "enabled": false } }
+ * or `.opencode/runtime.json` { "scout": { "enabled": false } }.
+ */
+
+import type { Plugin } from "@opencode-ai/plugin";
+import { existsSync, readFileSync, mkdirSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BLOCKED_DIRS = [
+  "node_modules",
+  "dist",
+  "build",
+  ".next",
+  ".nuxt",
+  ".output",
+  "__pycache__",
+  ".venv",
+  "venv",
+  ".env",
+  "vendor",
+  "target",
+  ".git",
+  "coverage",
+  ".nyc_output",
+];
+
+const BROAD_GLOB = [/^\*\*\/\*$/, /^\*\*\.\w+$/, /^\*\*\/\*\.\w+$/];
+
+const ALLOWED_CMD =
+  /^(npm|pnpm|yarn|bun|npx|pnpx|bunx|tsc|vite|esbuild|webpack|rollup|turbo|nx|jest|vitest|eslint|prettier|go|cargo|make|mvn|gradle|dotnet|docker|kubectl|helm|python3?|pip|uv|deno|bundle|rake|php|composer|ruby|mix)\b/;
+const VENV_EXEC = /(^|[\/\\])\.?venv[\/\\](bin|Scripts)[\/\\]/;
+const VENV_CREATE = /^(python3?|py)\s+.*-m\s+venv\s+|^uv\s+venv(\s|$)/;
+
+const GATED_TOOLS = new Set(["read", "write", "edit", "glob", "grep", "bash"]);
+
+const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+
+function isAllowedCommand(cmd: string): boolean {
+  const stripped = cmd
+    .trim()
+    .replace(/^(\w+=\S+\s+)+/, "")
+    .replace(/^(sudo|env|time)\s+/, "")
+    .trim();
+  return ALLOWED_CMD.test(stripped) || VENV_EXEC.test(stripped) || VENV_CREATE.test(stripped);
+}
+
+function isBlockedPath(p: string): string | null {
+  const segments = p.replace(/\\/g, "/").split("/");
+  return segments.find((seg) => BLOCKED_DIRS.includes(seg)) ?? null;
+}
+
+function isBroadGlob(p: string): boolean {
+  return BROAD_GLOB.some((rule) => rule.test(p.trim()));
+}
+
+function extractPaths(tool: string, args: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  if (!args) return out;
+
+  if (typeof args.filePath === "string") out.push(args.filePath);
+  if (typeof args.path === "string") out.push(args.path);
+  if (typeof args.pattern === "string" && tool === "glob") out.push(args.pattern);
+
+  if (tool === "bash" && typeof args.command === "string") {
+    const matches = args.command.match(/(?:cat|ls|find|head|tail)\s+(\S+)/g);
+    if (matches) {
+      for (const m of matches) {
+        const tail = m.trim().split(/\s+/).pop();
+        if (tail) out.push(tail);
+      }
+    }
+  }
+
+  return out.filter(Boolean);
+}
+
+function readRuntime(cwd: string): Record<string, any> {
+  try {
+    const file = join(cwd, ".opencode", "runtime.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+  } catch {
+    return {};
+  }
+}
+
+function logCrash(error: unknown): void {
+  try {
+    const logDir = join(PLUGIN_DIR, ".logs");
+    if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+    appendFileSync(
+      join(logDir, "hook-log.jsonl"),
+      JSON.stringify({
+        ts: new Date().toISOString(),
+        hook: "inspect-block",
+        status: "crash",
+        error: error instanceof Error ? error.message : String(error),
+      }) + "\n",
+    );
+  } catch {
+    // fail-open
+  }
+}
+
+export const InspectBlock: Plugin = async ({ directory }) => ({
+  "tool.execute.before": async (input, output) => {
+    try {
+      if (!GATED_TOOLS.has(input.tool)) return;
+
+      const runtime = readRuntime(directory);
+      if (runtime.scout?.enabled === false || runtime.inspect?.enabled === false) return;
+
+      const args = (output.args ?? {}) as Record<string, unknown>;
+
+      if (input.tool === "bash" && typeof args.command === "string") {
+        const cmds = args.command.split(/\s*(?:&&|\|\||;)\s*/).filter(Boolean);
+        if (cmds.every((c) => isAllowedCommand(c))) return;
+      }
+
+      if (input.tool === "glob" && typeof args.pattern === "string" && isBroadGlob(args.pattern)) {
+        throw new Error(
+          [
+            "SCOPE LIMIT EXCEEDED: Glob pattern is excessively broad",
+            `Requested Pattern: ${args.pattern}`,
+            "",
+            "Please narrow your scope (e.g., src/**/*.ts rather than **/*.ts).",
+          ].join("\n"),
+        );
+      }
+
+      const paths = extractPaths(input.tool, args);
+      for (const p of paths) {
+        const blocked = isBlockedPath(p);
+        if (blocked) {
+          throw new Error(
+            [
+              `SCOPE LIMIT EXCEEDED: Directory "${blocked}/" is explicitly forbidden`,
+              `Requested Path: ${p}`,
+              `Restricted zones: ${BLOCKED_DIRS.join(", ")}`,
+            ].join("\n"),
+          );
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith("SCOPE LIMIT EXCEEDED")) {
+        throw error;
+      }
+      logCrash(error);
+    }
+  },
+});