@haposoft/cafekit 0.8.17 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.8.17",
+  "version": "0.9.0",
   "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 task/spec is too vague to verify, use `/hapo:qs` or ask one grounded clarification 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:qs` when requirements are unclear 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",
+      "qs",
       "react-best-practices",
       "research",
       "specs",

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

@@ -29,6 +29,7 @@ User wants to...
 
 ```text
 User wants to...
+├── clarify missing requirements or acceptance criteria   -> /hapo:qs
 ├── 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...
+├── prepare stakeholder/customer questions before docs     -> /hapo:qs --batch
 ├── 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,12 @@ 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:qs -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
 | User intent | Suggested start |
 |---|---|
+| vague request, missing acceptance criteria, unclear scope, stakeholder questions | `/hapo:qs` |
 | 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 +82,5 @@ 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 missing information blocks workflow selection, use `/hapo:qs` before choosing brainstorm/specs/develop.
 - 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/qs/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: hapo:qs
+description: "Clarify vague requests before planning or implementation. Use when requirements, acceptance criteria, scope, constraints, stakeholder decisions, or next workflow readiness are unclear."
+argument-hint: "<request_or_context> [--batch|--spec-ready|--stakeholder]"
+version: 1.0.0
+---
+
+# QS Skill
+
+`hapo:qs` turns unclear intent into answerable questions and a readiness verdict. It is a clarification gate before `hapo:brainstorm`, `hapo:specs`, `hapo:docs --reconstruct`, `hapo:debug`, or `hapo:develop`.
+
+## Core Stance
+
+- Context before questions. Read the useful project/spec/docs/source context before asking.
+- Questions are work products. Make them specific, prioritized, and easy to answer.
+- One thing at a time in interactive mode.
+- Prefer multiple-choice options with a recommended default when the context supports it.
+- Do not design the solution unless the user explicitly moves to `hapo:brainstorm`.
+- Do not create specs or write code from this skill.
+
+<CLARIFICATION-ONLY-GATE>
+Do NOT implement, scaffold, edit product code, generate full specs, or make architecture decisions as final.
+The output is questions, assumptions, readiness, and next-step guidance.
+</CLARIFICATION-ONLY-GATE>
+
+## When To Use
+
+Use `hapo:qs` when:
+- The request is too vague to verify.
+- Acceptance criteria are missing.
+- Scope boundary is unclear.
+- Stakeholder/customer input is needed before specs.
+- The user asks "what should I ask?", "what is missing?", "can this go to specs?", or "is this clear enough?"
+- A spec/task has ambiguity that would make `hapo:develop` risky.
+- A legacy reconstruction or bug report lacks enough scope to start the correct workflow.
+
+Do not use it when:
+- The user asks for a direct factual answer that can be answered safely.
+- The user already gave exact output, acceptance criteria, scope, constraints, and target files.
+- The right action is clearly `hapo:debug`, `hapo:inspect`, `hapo:research`, or `hapo:docs --reconstruct`.
+
+## Modes
+
+- Default interactive mode: ask one highest-value question, then wait.
+- `--batch`: produce a grouped question list for a stakeholder/customer/team.
+- `--spec-ready`: audit whether the request can move to `hapo:specs`.
+- `--stakeholder`: write business-friendly questions with minimal implementation jargon.
+
+If multiple modes appear, use the most restrictive mode in this order: `--spec-ready`, `--batch`, `--stakeholder`, default.
+
+## Workflow
+
+### 1. Context Scout
+
+Read only enough context to make the questions concrete:
+- `README.md`
+- relevant `docs/`
+- relevant `specs/`
+- relevant source files when the request names a feature, module, API, UI, or bug
+
+Use `hapo:inspect` or focused search when the location is unclear. Do not scan the whole repo unless the question is about the whole repo.
+
+### 2. Build The Clarification Map
+
+Create a private map with these fields:
+
+```text
+Known facts:
+Assumptions:
+Missing decisions:
+Blocking unknowns:
+Non-blocking unknowns:
+Possible next workflow:
+```
+
+Classify each unknown:
+- `P0`: blocks correct next action.
+- `P1`: high-risk ambiguity; should answer before implementation.
+- `P2`: useful detail; can defer.
+
+### 3. Ask Or Report
+
+Default interactive mode:
+- Ask exactly one `P0` question.
+- Make it concrete and grounded in observed context.
+- If possible, provide 2-3 options.
+- Put the recommended option first and explain the tradeoff in one sentence.
+
+`--batch` or `--stakeholder`:
+- Produce grouped questions by priority.
+- Keep each question answerable.
+- Include recommended options only when they are justified by context.
+
+`--spec-ready`:
+- Return a readiness checklist and verdict.
+- Do not ask a long question list unless verdict is `not-ready`.
+
+### 4. Readiness Verdict
+
+End with one of:
+- `not-ready`: missing P0 decisions.
+- `brainstorm-ready`: enough to explore solution options, but not enough for specs.
+- `specs-ready`: enough to run `/hapo:specs <request>`.
+- `develop-ready`: an approved spec/task exists and no blocking ambiguity remains.
+
+### 5. Next Step
+
+Suggest exactly one next command:
+- `/hapo:qs ...` when another clarification round is required.
+- `/hapo:brainstorm ...` when design/options are still open.
+- `/hapo:specs ...` when requirements are clear enough.
+- `/hapo:debug ...` when the issue is a bug with unknown root cause.
+- `/hapo:docs --reconstruct <scope>` when the task is legacy/as-is docs.
+- `/hapo:develop <feature>` only when an approved spec/task is already clear.
+
+## Output Formats
+
+### Default Interactive Output
+
+```markdown
+**Context Read**
+- ...
+
+**Known**
+- ...
+
+**Blocking Unknown**
+- P0: ...
+
+**Question**
+...
+
+**Options**
+- A. ... (Recommended) - ...
+- B. ... - ...
+- C. ... - ...
+
+**Readiness**
+not-ready | brainstorm-ready | specs-ready | develop-ready
+
+**Next**
+/hapo:qs ...
+```
+
+### Batch Output
+
+Use `templates/qs.md` when the user asks to save or document the question set.
+
+```markdown
+**Question Set**
+
+**P0 - Must Answer**
+1. ...
+
+**P1 - Should Answer**
+1. ...
+
+**P2 - Can Defer**
+1. ...
+
+**Assumptions To Confirm**
+- ...
+
+**Readiness**
+...
+
+**Next**
+...
+```
+
+## Quality Bar
+
+- Every P0 question must explain what decision it unlocks.
+- No generic "please clarify" questions.
+- No more than one interactive question per response.
+- No implementation plan unless the next command is `hapo:brainstorm` or `hapo:specs`.
+- If no P0/P1 unknown exists, do not invent questions. Say it is ready and name the next command.

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

@@ -0,0 +1,30 @@
+# Question Set: {{TITLE}}
+
+## Context Read
+- {{CONTEXT_ITEM}}
+
+## Known Facts
+- {{KNOWN_FACT}}
+
+## Assumptions
+- {{ASSUMPTION}}
+
+## P0 - Must Answer
+1. **Question:** {{P0_QUESTION}}
+   - **Why it matters:** {{WHY_IT_MATTERS}}
+   - **Recommended answer:** {{RECOMMENDED_ANSWER}}
+   - **Other options:** {{OTHER_OPTIONS}}
+
+## P1 - Should Answer
+1. **Question:** {{P1_QUESTION}}
+   - **Risk if unanswered:** {{RISK}}
+
+## P2 - Can Defer
+1. **Question:** {{P2_QUESTION}}
+   - **Can defer until:** {{DEFER_POINT}}
+
+## Readiness Verdict
+`not-ready | brainstorm-ready | specs-ready | develop-ready`
+
+## Next Command
+`/hapo:qs ... | /hapo:brainstorm ... | /hapo:specs ... | /hapo:debug ... | /hapo:docs --reconstruct ... | /hapo:develop ...`

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.
+- `/qs <request-or-context> [--batch|--spec-ready|--stakeholder]`: clarify requirements, missing decisions, and next workflow readiness.
 - `/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 task/spec is too vague to verify, use `/qs` or ask one grounded clarification 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 `/qs` when requirements are unclear 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);
+    }
+  },
+});