@cbartens/bkit 6.1.0 → 6.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (317) hide show
  1. package/.bkit/README.md +14 -12
  2. package/.bkit/core/.agents/docs.md +1 -11
  3. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +30 -9
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +25 -27
  5. package/.bkit/core/.agents/rules.md +22 -9
  6. package/.bkit/core/.bkit/README.md +13 -11
  7. package/.bkit/core/.bkit/authoring.md +58 -13
  8. package/.bkit/core/.bkit/cli.md +43 -33
  9. package/.bkit/core/.bkit/cloud.md +93 -30
  10. package/.bkit/core/.bkit/install.md +55 -16
  11. package/.bkit/core/.bkit/jsonl.md +24 -7
  12. package/.bkit/core/.bkit/pipeline.md +8 -8
  13. package/.bkit/core/.bkit/prompts.md +160 -43
  14. package/.bkit/core/.bkit/providers.md +99 -36
  15. package/.bkit/core/.bkit/templates.md +167 -37
  16. package/.bkit/core/.bkit/trackers.md +39 -6
  17. package/.bkit/core/.bkit/workflows.md +344 -136
  18. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +50 -27
  19. package/.bkit/core/.claude/hooks/bkit-preflight.sh +11 -11
  20. package/.bkit/core/.codex/hooks/bkit-gateguard.cjs +13 -8
  21. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +14 -25
  22. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +20 -9
  23. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +8 -8
  24. package/.bkit/core/.opencode/plugin/bkit-gateguard.js +14 -4
  25. package/.bkit/core/.opencode/plugin/bkit-guardrails.js +114 -0
  26. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +1 -1
  27. package/.bkit/core/docs/templates/bkit-audit-adoption.md +30 -6
  28. package/.bkit/core/docs/templates/bkit-audit-agents.md +1 -1
  29. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +1 -1
  30. package/.bkit/core/docs/templates/bkit-audit-analytics.md +1 -1
  31. package/.bkit/core/docs/templates/bkit-audit-annotations.md +1 -1
  32. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +1 -1
  33. package/.bkit/core/docs/templates/bkit-audit-app-store.md +1 -1
  34. package/.bkit/core/docs/templates/bkit-audit-architecture.md +1 -1
  35. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +2 -2
  36. package/.bkit/core/docs/templates/bkit-audit-config.md +3 -2
  37. package/.bkit/core/docs/templates/bkit-audit-cost.md +1 -1
  38. package/.bkit/core/docs/templates/bkit-audit-coverage.md +1 -1
  39. package/.bkit/core/docs/templates/bkit-audit-database.md +3 -3
  40. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +1 -1
  41. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +1 -1
  42. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +3 -3
  43. package/.bkit/core/docs/templates/bkit-audit-documentation.md +32 -2
  44. package/.bkit/core/docs/templates/bkit-audit-duplication.md +1 -1
  45. package/.bkit/core/docs/templates/bkit-audit-failures.md +1 -1
  46. package/.bkit/core/docs/templates/bkit-audit-flakes.md +2 -2
  47. package/.bkit/core/docs/templates/bkit-audit-gates.md +5 -3
  48. package/.bkit/core/docs/templates/bkit-audit-issues.md +1 -1
  49. package/.bkit/core/docs/templates/bkit-audit-llm.md +2 -2
  50. package/.bkit/core/docs/templates/bkit-audit-logs.md +1 -1
  51. package/.bkit/core/docs/templates/bkit-audit-models.md +2 -2
  52. package/.bkit/core/docs/templates/bkit-audit-privacy.md +1 -1
  53. package/.bkit/core/docs/templates/bkit-audit-prompts.md +1 -1
  54. package/.bkit/core/docs/templates/bkit-audit-red-team.md +2 -2
  55. package/.bkit/core/docs/templates/bkit-audit-reliability.md +3 -2
  56. package/.bkit/core/docs/templates/bkit-audit-repo.md +1 -1
  57. package/.bkit/core/docs/templates/bkit-audit-security.md +1 -1
  58. package/.bkit/core/docs/templates/bkit-audit-slop.md +1 -1
  59. package/.bkit/core/docs/templates/bkit-audit-testing.md +3 -2
  60. package/.bkit/core/docs/templates/bkit-audit-usability.md +1 -1
  61. package/.bkit/core/docs/templates/bkit-plan.md +38 -8
  62. package/.bkit/core/engine/checks/after/auth.ts +118 -47
  63. package/.bkit/core/engine/checks/after/github.ts +161 -37
  64. package/.bkit/core/engine/checks/after/index.ts +18 -3
  65. package/.bkit/core/engine/checks/after/tools.ts +245 -1
  66. package/.bkit/core/engine/checks/before/files.ts +59 -1
  67. package/.bkit/core/engine/checks/before/index.ts +8 -0
  68. package/.bkit/core/engine/checks/status-holes.ts +20 -26
  69. package/.bkit/core/engine/checks/tips/catalogue.ts +107 -10
  70. package/.bkit/core/engine/checks/tips/detect.ts +36 -3
  71. package/.bkit/core/engine/checks/tips/index.ts +1 -1
  72. package/.bkit/core/engine/cli.ts +13 -13
  73. package/.bkit/core/engine/commands/ci/ci.ts +124 -19
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/doctor.ts +5 -5
  76. package/.bkit/core/engine/commands/install/install.ts +28 -25
  77. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  78. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  79. package/.bkit/core/engine/commands/land.ts +2 -3
  80. package/.bkit/core/engine/commands/lib.ts +394 -39
  81. package/.bkit/core/engine/commands/registry.ts +1 -1
  82. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  83. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  84. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  85. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  86. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  87. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  88. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  89. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  90. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  91. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  92. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  93. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  94. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  95. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  96. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  97. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  98. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  99. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  100. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  101. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  102. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  103. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  104. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  105. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  106. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  107. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  108. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  109. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  110. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  111. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  112. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  113. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  114. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  115. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  116. package/.bkit/core/engine/install/managed-block.ts +105 -0
  117. package/.bkit/core/engine/install/manifest.ts +7 -1
  118. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  119. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  120. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  121. package/.bkit/core/engine/install/modules/core.ts +202 -26
  122. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  123. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  124. package/.bkit/core/engine/install/project-docs.ts +650 -0
  125. package/.bkit/core/engine/install/template-copies.ts +58 -5
  126. package/.bkit/core/engine/install/write.ts +128 -7
  127. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  128. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  129. package/.bkit/core/engine/ledgers/status.ts +604 -8
  130. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  131. package/.bkit/core/engine/render/trackers.ts +46 -11
  132. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  133. package/.bkit/core/engine/shared/settings.ts +12 -1
  134. package/.bkit/core/engine/shared/text.ts +14 -0
  135. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  136. package/.bkit/core/engine/tools/instructions.ts +116 -20
  137. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  138. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  139. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  140. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  141. package/.bkit/core/hooks/guardrails-read.js +3 -3
  142. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  143. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  144. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  145. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  146. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  147. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  148. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  149. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  150. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  151. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  152. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  153. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  154. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  155. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  156. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  157. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  158. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  159. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  162. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  163. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  164. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  165. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  166. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  167. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  168. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  169. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  170. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  172. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  173. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  174. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  175. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  176. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  177. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  178. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  179. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  180. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  181. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  182. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  183. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  184. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  185. package/.bkit/core/workflows/bkit-auto.md +23 -11
  186. package/.bkit/core/workflows/bkit-build.md +331 -100
  187. package/.bkit/core/workflows/bkit-debug.md +135 -64
  188. package/.bkit/core/workflows/bkit-design.md +58 -32
  189. package/.bkit/core/workflows/bkit-plan.md +73 -45
  190. package/.bkit/core/workflows/bkit-ship.md +233 -167
  191. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  192. package/.bkit/shared/.bkit/.env.example +5 -0
  193. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  194. package/.bkit/shared/.claude/settings.json +5 -1
  195. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  196. package/.bkit/shared/.cursor/hooks.json +1 -1
  197. package/.bkit/shared/.opencode/opencode.json +11 -2
  198. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  199. package/.bkit/templates/.cursor/Dockerfile +7 -7
  200. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  201. package/.bkit/templates/.github/dependabot.yml +5 -0
  202. package/.bkit/templates/.github/renovate.json5 +5 -3
  203. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  204. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  205. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  206. package/.bkit/templates/.husky/pre-push +123 -6
  207. package/.bkit/templates/context/bkit-serena.md +1 -1
  208. package/.bkit/templates/context/bkit-vercel.md +103 -59
  209. package/.bkit/templates/docs/architecture.md +98 -0
  210. package/.bkit/templates/docs/capabilities.md +33 -37
  211. package/.bkit/templates/docs/components.md +142 -0
  212. package/.bkit/templates/docs/data-schema.md +87 -0
  213. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  214. package/.bkit/templates/docs/design.md +117 -0
  215. package/.bkit/templates/docs/noise.md +54 -0
  216. package/.bkit/templates/docs/observability.md +99 -0
  217. package/.bkit/templates/docs/security.md +137 -0
  218. package/.bkit/templates/docs/setup.md +93 -0
  219. package/.bkit/templates/docs/technology.md +70 -0
  220. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  221. package/.bkit/templates/scripts/ci/bkit-check-accepted-divergences.mjs +1 -6
  222. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  223. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +314 -28
  224. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +500 -1
  225. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  226. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +91 -62
  227. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  228. package/.bkit/templates/slop-scan.config.json +2 -0
  229. package/CHANGELOG.md +79 -0
  230. package/DETAILS.md +661 -0
  231. package/README.md +73 -604
  232. package/dist/checks/after/auth.js +114 -46
  233. package/dist/checks/after/github.js +138 -35
  234. package/dist/checks/after/index.js +16 -4
  235. package/dist/checks/after/tools.js +224 -1
  236. package/dist/checks/before/files.js +59 -1
  237. package/dist/checks/before/index.js +7 -1
  238. package/dist/checks/status-holes.js +20 -21
  239. package/dist/checks/tips/catalogue.js +99 -10
  240. package/dist/checks/tips/detect.js +35 -3
  241. package/dist/checks/tips/index.js +1 -1
  242. package/dist/cli.js +13 -13
  243. package/dist/commands/ci/ci.js +113 -20
  244. package/dist/commands/ci/push-gate.js +79 -44
  245. package/dist/commands/install/doctor.js +5 -5
  246. package/dist/commands/install/install.js +23 -22
  247. package/dist/commands/install/uninstall.js +36 -30
  248. package/dist/commands/install/upgrade.js +10 -2
  249. package/dist/commands/land.js +2 -3
  250. package/dist/commands/lib.js +323 -25
  251. package/dist/commands/workflow/branches.js +312 -72
  252. package/dist/commands/workflow/challenge.js +66 -13
  253. package/dist/commands/workflow/context.js +46 -10
  254. package/dist/commands/workflow/counters.js +231 -23
  255. package/dist/commands/workflow/decisions.js +221 -106
  256. package/dist/commands/workflow/disk.js +2 -1
  257. package/dist/commands/workflow/feature-base.js +60 -0
  258. package/dist/commands/workflow/issues.js +243 -15
  259. package/dist/commands/workflow/junit.js +137 -0
  260. package/dist/commands/workflow/ledgers.js +726 -112
  261. package/dist/commands/workflow/locks.js +150 -29
  262. package/dist/commands/workflow/loops.js +67 -0
  263. package/dist/commands/workflow/open-decision.js +199 -0
  264. package/dist/commands/workflow/plan-blocks.js +6 -0
  265. package/dist/commands/workflow/plans.js +1 -1
  266. package/dist/commands/workflow/prs.js +272 -16
  267. package/dist/commands/workflow/repo.js +1 -1
  268. package/dist/commands/workflow/run-facts.js +6 -0
  269. package/dist/commands/workflow/runs.js +747 -155
  270. package/dist/commands/workflow/runtime.js +8 -4
  271. package/dist/commands/workflow/status.js +259 -13
  272. package/dist/commands/workflow/step-table.js +41 -15
  273. package/dist/commands/workflow/steps.js +530 -26
  274. package/dist/commands/workflow/summary-findings.js +1 -1
  275. package/dist/commands/workflow/summary.js +289 -8
  276. package/dist/commands/workflow/tasks.js +294 -27
  277. package/dist/commands/workflow/tests-base.js +266 -0
  278. package/dist/commands/workflow/tests-changed.js +130 -56
  279. package/dist/commands/workflow/tests-jump.js +77 -0
  280. package/dist/commands/workflow/tests.js +608 -131
  281. package/dist/commands/workflow/tracker.js +920 -112
  282. package/dist/commands/workflow/workflows.js +80 -59
  283. package/dist/commands/workflow/worktrees.js +387 -58
  284. package/dist/install/cloud-env.js +32 -10
  285. package/dist/install/managed-block.js +101 -0
  286. package/dist/install/manifest.js +7 -1
  287. package/dist/install/modules/claude.js +6 -2
  288. package/dist/install/modules/cloud.js +73 -86
  289. package/dist/install/modules/codex.js +9 -2
  290. package/dist/install/modules/core.js +190 -27
  291. package/dist/install/modules/opencode.js +18 -23
  292. package/dist/install/network-allowlist.js +8 -3
  293. package/dist/install/project-docs.js +551 -0
  294. package/dist/install/template-copies.js +55 -5
  295. package/dist/install/write.js +117 -5
  296. package/dist/ledgers/journal.js +10 -8
  297. package/dist/ledgers/migrate.js +20 -9
  298. package/dist/ledgers/status.js +461 -8
  299. package/dist/ledgers/telemetry.js +71 -13
  300. package/dist/render/trackers.js +21 -12
  301. package/dist/shared/package-manager.js +7 -2
  302. package/dist/shared/settings.js +8 -0
  303. package/dist/shared/text.js +13 -0
  304. package/dist/tools/instructions-sources.js +1 -0
  305. package/dist/tools/instructions.js +97 -24
  306. package/package.json +23 -15
  307. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  308. package/.bkit/shared/docs/architecture.md +0 -16
  309. package/.bkit/shared/docs/data-schema.md +0 -16
  310. package/.bkit/shared/docs/design.md +0 -38
  311. package/.bkit/shared/docs/noise.md +0 -20
  312. package/.bkit/shared/docs/observability.md +0 -22
  313. package/.bkit/shared/docs/security.md +0 -62
  314. package/.bkit/shared/docs/setup.md +0 -52
  315. package/.bkit/shared/docs/technology.md +0 -15
  316. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  317. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -1,26 +1,29 @@
1
1
  #!/usr/bin/env node
2
- // bkit-guardrails.cjs — bkit shell advisories (Claude Code).
2
+ // bkit-guardrails.cjs — bkit shell deny tier and advisories (Claude Code).
3
3
  //
4
4
  // Twin of `.cursor/hooks/bkit-guardrails.cjs` and `.codex/hooks/bkit-guardrails.cjs`: bkit
5
- // generates the same shell detection into all three at install (bkit's
6
- // `core/hooks/guardrails-shell.js`). Wired from `.claude/settings.json` → PreToolUse,
7
- // matcher `Bash`.
5
+ // generates the same shell parser and deny tier into all of them at install (bkit's
6
+ // `core/hooks/guardrails-shell.js` and `guardrails-deny.js`). Wired from
7
+ // `.claude/settings.json` → PreToolUse, matcher `Bash`.
8
8
  //
9
- // SCOPE — the two shell checks a command-PREFIX permission table cannot express:
9
+ // SCOPE — the shell checks a command-PREFIX permission table cannot express:
10
10
  //
11
- // 1. URL HOSTS. `Bash(curl:*)` matches a prefix, never a URL host. This hook flags a
11
+ // 1. DENY TIER. A git force push, `rm -rf` of a filesystem root and `chmod -R 777 /`
12
+ // are refused, read through wrappers (`env -u FOO`, `timeout 30`) that a prefix
13
+ // pattern cannot see past, and not refused when they only appear inside quotes.
14
+ // 2. URL HOSTS. `Bash(curl:*)` matches a prefix, never a URL host. This hook flags a
12
15
  // curl / wget whose URL host is off the network allowlist.
13
- // 2. SHELL-AS-EDIT-CHANNEL. `sed -i` and redirection into a source file bypass every
16
+ // 3. SHELL-AS-EDIT-CHANNEL. `sed -i` and redirection into a source file bypass every
14
17
  // pre-edit gate (GateGuard only sees Edit/Write/MultiEdit). Detection parses the
15
18
  // target path.
16
19
  //
17
- // ADVISORY ONLY — this hook NEVER denies and NEVER asks; it emits `additionalContext`.
18
- // `deny` rows live in settings.json and are evaluated BEFORE any hook. The permission
19
- // table and the auto-mode classifier are what stop commands.
20
+ // REFUSES THE DENY TIER ONLY — it prints `permissionDecision: "deny"` and exits 0 (the
21
+ // `.claude/settings.json` registration ends in `|| true`, which swallows a non-zero exit).
22
+ // It NEVER asks: the URL-host and edit checks are `additionalContext` advice.
20
23
  //
21
24
  // CONTRACT — do not regress:
22
25
  // - FAIL OPEN: one top-level catch swallows every error and exits 0.
23
- // - NEVER BLOCKS: no `permissionDecision` is ever emitted from the managed block.
26
+ // - DENY IS REAL: the deny tier returns `{ verdict: "deny" }` and the driver blocks.
24
27
  // - PURE ENGINE: everything between the markers is a decision engine only — no stdin
25
28
  // read, no stdout write. Add your own gates in the driver below the block.
26
29
  //
@@ -34,38 +37,50 @@
34
37
  // {{BKIT_MANAGED_MARKER}}
35
38
 
36
39
  const fs = require("node:fs");
40
+ const os = require("node:os");
37
41
  const path = require("node:path");
38
42
 
43
+ // {{BKIT_PART gateguard-engine.js}}
44
+
39
45
  // {{BKIT_PART guardrails-shell.js}}
40
46
 
47
+ // {{BKIT_PART guardrails-deny.js}}
48
+
41
49
  const SHELL_TOOL_NAMES = new Set(["Bash", "bash"]);
42
50
 
43
51
  /**
44
- * Entry point — pure. Returns `{ context }` when bkit has something to say about this
45
- * call, or `null` when it does not. Never returns a blocking decision: see the header.
52
+ * Entry point — pure. Returns `{ verdict: "deny", reason }` for a command the deny tier
53
+ * refuses, `{ context }` when bkit has advice about this call, or `null` when it does not.
46
54
  */
47
55
  function bkitGuardrails(payload) {
48
56
  if (!payload || typeof payload !== "object") return null;
49
57
  if (!SHELL_TOOL_NAMES.has(payload.tool_name)) return null;
50
58
  const input = payload.tool_input || {};
51
- const cmd = Array.isArray(input.command) ? input.command.join(" ") : input.command;
59
+ const cmd = shellCommandText(input.command);
52
60
  if (typeof cmd !== "string") return null;
53
61
  const c = cmd.trim();
54
62
  if (!c) return null;
55
63
 
56
- const notes = [];
57
- if (usesFetch(c) && !curlWgetHostAllowed(c, hookDirs(payload))) {
58
- notes.push(
59
- "bkit guardrails: outbound fetch to a host that is not on this repo's network allowlist " +
60
- "(.agents/context.md § allowed-domains, plus bkit's shipped tooling hosts). The command is allowed.\n" +
61
- "Confirm the destination is intended before you rely on the result.\n" +
62
- "If the host is a standing dependency, add it to allowed-domains.",
63
- );
64
+ const ctx = hookContext(payload);
65
+ const st = newEvidence(ctx);
66
+ const cmds = shellCommands(c, st);
67
+ const denied = denyRule(cmds);
68
+ if (denied) {
69
+ const refusal = composeAdvice({ tier: "deny", ...denied }, "claude", ADVICE_BUDGETS.claude);
70
+ return { verdict: "deny", reason: refusal.text };
64
71
  }
65
- const edits = shellEditTargets(c);
66
- if (edits.length > 0) notes.push(shellEditAdvisory(edits));
67
-
68
- return notes.length > 0 ? { context: notes.join("\n\n") } : null;
72
+ const fetch = usesFetch(cmds) && !curlWgetHostAllowed(cmds, ctx.dirs);
73
+ const edits = shellEditTargets(cmds, st);
74
+ const found = hasEditEvidence(edits);
75
+ if (!fetch && !found) return null;
76
+ const advice = composeAdvice(
77
+ { tier: fetch ? "fetch" : "edit", edits: found ? edits : undefined },
78
+ "claude",
79
+ ADVICE_BUDGETS.claude,
80
+ { command: c, ctx, session: payload.session_id, agent: payload.agent_id },
81
+ );
82
+ acknowledgeSelected(advice.selected);
83
+ return { context: advice.text };
69
84
  }
70
85
 
71
86
  // bkit:end
@@ -85,7 +100,15 @@ try {
85
100
  if (raw.trim()) {
86
101
  const result = bkitGuardrails(JSON.parse(raw));
87
102
  if (result) {
88
- emit({ hookEventName: "PreToolUse", additionalContext: result.context });
103
+ emit(
104
+ result.verdict === "deny"
105
+ ? {
106
+ hookEventName: "PreToolUse",
107
+ permissionDecision: "deny",
108
+ permissionDecisionReason: result.reason,
109
+ }
110
+ : { hookEventName: "PreToolUse", additionalContext: result.context },
111
+ );
89
112
  }
90
113
  }
91
114
  } catch {
@@ -1,12 +1,12 @@
1
1
  #!/usr/bin/env bash
2
2
  # bkit-preflight.sh — Claude Code SessionStart hook
3
3
  #
4
- # Validates Linear issue state before any background/cloud session does bkit
4
+ # Validates tracker issue state before any issue-carrying session does bkit
5
5
  # work. Refuses the session if the issue isn't approved for automation.
6
6
  #
7
- # Trigger: LINEAR_ISSUE_ID env var present (proxy for non-IDE session).
8
- # Guards: `bkit:auto` label present; issue state not in {Cancelled, Done}.
9
- # Setup: See `.bkit/README.md` § Linear setup.
7
+ # Trigger: LINEAR_ISSUE_ID or GITHUB_ISSUE_ID env var present.
8
+ # Guards: `bkit:auto` label present; issue state not terminal by category.
9
+ # Setup: See `.bkit/README.md` for the configured tracker.
10
10
  #
11
11
  # IMPORTANT — Claude Code SessionStart hooks CANNOT block the session: any
12
12
  # non-zero exit is treated as non-blocking (docs.claude.com/docs/en/hooks.md).
@@ -14,8 +14,8 @@
14
14
  # HARD STOP instruction) AND `stderr` (visible to the user). Exit code is
15
15
  # informational only.
16
16
  #
17
- # bkit generates the managed block at install: the Linear guard and the rules-read
18
- # advisory are shared with the Cursor hook (bkit's `hooks/preflight-linear.sh` and
17
+ # bkit generates the managed block at install: the tracker guard and the rules-read
18
+ # advisory are shared with the Cursor hook (bkit's `hooks/preflight-tracker.sh` and
19
19
  # `hooks/preflight-rules.sh`); the trigger, the brew check and the output shape below
20
20
  # are Claude's own.
21
21
 
@@ -32,7 +32,7 @@ INPUT=$(cat)
32
32
  # emit_context — Claude SessionStart expects ONE JSON document
33
33
  # { hookSpecificOutput: { hookEventName, additionalContext } } on stdout. Each call
34
34
  # accumulates its string; the EXIT trap writes the document once, so the advisory and
35
- # the Linear guard result ride one document (two documents are unparseable).
35
+ # the tracker guard result ride one document (two documents are unparseable).
36
36
  # (Cursor variant: emits { additional_context: ... } directly.)
37
37
  BKIT_CONTEXT=""
38
38
  emit_context() {
@@ -52,7 +52,7 @@ bkit_json_escape() {
52
52
  s=${s//$'\t'/\\t}
53
53
  # The rest of the C0 range (U+0000–U+001F) — bash cannot hold NUL, so 1–31 minus the
54
54
  # three above. A raw control byte makes the whole document unparseable and the host
55
- # discards it, taking the advisory and the Linear guard result with it.
55
+ # discards it, taking the advisory and the tracker guard result with it.
56
56
  for (( i = 1; i < 32; i++ )); do
57
57
  case $i in 9 | 10 | 13) continue ;; esac
58
58
  printf -v oct '%03o' "$i"
@@ -74,9 +74,9 @@ trap bkit_write_document EXIT
74
74
  # {{BKIT_PART preflight-rules.sh}}
75
75
 
76
76
  # IDE session detection — the advisory above already fired; nothing else runs here.
77
- # Claude has no native is-background flag, so we use empty LINEAR_ISSUE_ID as the proxy.
77
+ # Claude has no native is-background flag, so we use the issue env vars as the proxy.
78
78
  # (Cursor variant: parses `is_background_agent` from stdin JSON.)
79
- if [[ -z "${LINEAR_ISSUE_ID:-}" ]]; then
79
+ if [[ -z "${LINEAR_ISSUE_ID:-}" && -z "${GITHUB_ISSUE_ID:-}" ]]; then
80
80
  exit 0
81
81
  fi
82
82
 
@@ -100,6 +100,6 @@ if [[ "$(uname)" == "Darwin" ]]; then
100
100
  fi
101
101
  fi
102
102
 
103
- # {{BKIT_PART preflight-linear.sh}}
103
+ # {{BKIT_PART preflight-tracker.sh}}
104
104
 
105
105
  # <!-- bkit:end -->
@@ -79,14 +79,19 @@ function bkitGateguard(payload) {
79
79
  const input = payload.tool_input || {};
80
80
  const cwd = typeof payload.cwd === "string" ? payload.cwd : "";
81
81
  const sessionId = dedupKey(payload.session_id, payload.agent_id);
82
- // One patch can touch several files. Advises on the first not-yet-warned target, so a
83
- // new file after an already-warned one still gets its advisory.
84
- const target = parseApplyPatchTargets(input.command, cwd).find(
85
- (t) => !alreadyWarned(sessionId, t.file),
86
- );
87
- if (!target) return null;
88
- // `*** Add File:` IS the new-file signal; no existence probe.
89
- return firstTouchAdvice(target.file, sessionId, target.isNew);
82
+ // One patch can touch several files. Every not-yet-warned target is prepared (nothing is
83
+ // recorded), complete blocks are selected inside Codex's output budget, and only the
84
+ // selected blocks are acknowledged; the rest stay eligible for a later edit.
85
+ const blocks = [];
86
+ const seen = new Set();
87
+ for (const t of parseApplyPatchTargets(input.command, cwd)) {
88
+ // `*** Add File:` IS the new-file signal; no existence probe.
89
+ const prepared = prepareAdvice(t.file, sessionId, t.isNew, cwd);
90
+ if (!prepared || seen.has(prepared.key)) continue;
91
+ seen.add(prepared.key);
92
+ blocks.push(prepared);
93
+ }
94
+ return deliverAdvice(blocks, ADVICE_BUDGETS.codex, true);
90
95
  }
91
96
 
92
97
  // bkit:end
@@ -36,10 +36,15 @@
36
36
  // {{BKIT_MANAGED_MARKER}}
37
37
 
38
38
  const fs = require("node:fs");
39
+ const os = require("node:os");
39
40
  const path = require("node:path");
40
41
 
42
+ // {{BKIT_PART gateguard-engine.js}}
43
+
41
44
  // {{BKIT_PART guardrails-shell.js}}
42
45
 
46
+ // {{BKIT_PART guardrails-deny.js}}
47
+
43
48
  // {{BKIT_PART guardrails-tiers.js}}
44
49
 
45
50
  /** Verdicts mirror the Cursor hook's tiers so the shared gate table reads identically. */
@@ -57,32 +62,16 @@ function deny(reason) {
57
62
 
58
63
  /**
59
64
  * @param {string} cmd
60
- * @param {string[]} dirs where to look for the network allowlist (`hookDirs`)
65
+ * @param {{ cwd?: string, root?: string, dirs: string[] }} ctx the call's directories (`hookContext`)
61
66
  */
62
- function decideShell(cmd, dirs) {
67
+ function decideShell(cmd, ctx, session) {
63
68
  const c = String(cmd || "").trim();
64
- const v = classifyShell(c, dirs);
69
+ const v = classifyShell(c, "codex", ctx);
65
70
  if (!v) return allow();
66
- switch (v.tier) {
67
- case "deny":
68
- return deny(`Blocked by bkit Codex guardrails: ${v.what}. ${v.fix}`);
69
- case "ask":
70
- // Advisory on this host (Codex cannot prompt).
71
- return ask(
72
- `bkit Codex guardrails: this destructive or privileged command (${v.what}) ran without confirmation, because Codex cannot prompt for one. It is on the PROHIBITED list in every bkit workflow.\nTell the user that you ran it.\nIf the user did not ask for this exact command, NEVER run it again.\n\`git clean\` and \`git checkout -- .\` destroy untracked files and uncommitted work, which no reflog can recover.\nCommand: ${c}`,
73
- );
74
- case "secret":
75
- return ask(
76
- `bkit Codex guardrails: this command read ${v.path}, an env, secrets or private-key file, without confirmation, because Codex cannot prompt for one.\nNEVER print secret values.\nPrefer direnv or documented non-secret examples.\nCommand: ${c}`,
77
- );
78
- case "fetch":
79
- return ask(
80
- `bkit Codex guardrails: outbound fetch to a host that is not on the network allowlist.\nConfirm the destination is intended before you rely on the result.\nCommand: ${c}`,
81
- );
82
- default:
83
- // Shell-as-edit-channel: advisory on every host, never a block.
84
- return ask(shellEditAdvisory(v.edits));
85
- }
71
+ const advice = composeAdvice(v, "codex", ADVICE_BUDGETS.codex, { command: c, ctx, session });
72
+ acknowledgeSelected(advice.selected);
73
+ // Every tier but deny is advisory on this host (Codex cannot prompt).
74
+ return v.tier === "deny" ? deny(advice.text) : ask(advice.text);
86
75
  }
87
76
 
88
77
  /**
@@ -101,9 +90,9 @@ function bkitGuardrails(payload) {
101
90
  if (!SHELL_TOOL_NAMES.has(tool)) return null;
102
91
  const input = payload.tool_input || {};
103
92
  // Codex passes the command as a string, or as an argv array for some shells.
104
- const cmd = Array.isArray(input.command) ? input.command.join(" ") : input.command;
93
+ const cmd = shellCommandText(input.command);
105
94
  if (typeof cmd !== "string") return null;
106
- const decision = decideShell(cmd, hookDirs(payload));
95
+ const decision = decideShell(cmd, hookContext(payload), payload.session_id);
107
96
  return decision.verdict === "allow" ? null : decision;
108
97
  }
109
98
 
@@ -28,10 +28,15 @@
28
28
  // {{BKIT_MANAGED_MARKER}}
29
29
 
30
30
  const fs = require("node:fs");
31
+ const os = require("node:os");
31
32
  const path = require("node:path");
32
33
 
34
+ // {{BKIT_PART gateguard-engine.js}}
35
+
33
36
  // {{BKIT_PART guardrails-shell.js}}
34
37
 
38
+ // {{BKIT_PART guardrails-deny.js}}
39
+
35
40
  // {{BKIT_PART guardrails-tiers.js}}
36
41
 
37
42
  // {{BKIT_PART guardrails-read.js}}
@@ -58,34 +63,36 @@ function deny(userMessage, agentMessage) {
58
63
 
59
64
  /**
60
65
  * @param {string} cmd
61
- * @param {string[]} dirs where to look for the network allowlist (`hookDirs`)
66
+ * @param {{ cwd?: string, root?: string, dirs: string[] }} ctx the call's directories (`hookContext`)
62
67
  */
63
- function decideShell(cmd, dirs) {
68
+ function decideShell(cmd, ctx, session) {
64
69
  const c = cmd.trim();
65
- const v = classifyShell(c, dirs);
70
+ const v = classifyShell(c, "cursor", ctx);
66
71
  if (!v) return allow();
72
+ const advice = composeAdvice(v, "cursor", ADVICE_BUDGETS.cursor, { command: c, ctx, session });
73
+ acknowledgeSelected(advice.selected);
67
74
  switch (v.tier) {
68
75
  case "deny":
69
- return deny(`Blocked: ${v.what} is denied by bkit Cursor guardrails.`, v.fix);
76
+ return deny(`Blocked: ${v.what} is denied by bkit Cursor guardrails.`, advice.text);
70
77
  case "ask":
71
78
  return ask(
72
79
  `bkit Cursor guardrails: confirm this destructive or privileged shell command (${v.what}).`,
73
- `Command requires confirmation: ${c}`,
80
+ advice.text,
74
81
  );
75
82
  case "secret":
76
83
  return ask(
77
84
  "bkit Cursor guardrails: confirm a shell read of an env, secrets or private-key file.",
78
- `Reading ${v.path} through the shell may expose secrets.\nPrefer direnv or documented non-secret examples.\nCommand: ${c}`,
85
+ advice.text,
79
86
  );
80
87
  case "fetch":
81
88
  return ask(
82
89
  "bkit Cursor guardrails: confirm an outbound curl or wget to a host that is not on the network allowlist.",
83
- `Command requires confirmation: ${c}`,
90
+ advice.text,
84
91
  );
85
92
  default:
86
93
  // Shell-as-edit-channel: ADVISORY, never a block — allow plus an `agent_message`
87
94
  // naming the edited paths.
88
- return { permission: "allow", agent_message: shellEditAdvisory(v.edits) };
95
+ return { permission: "allow", agent_message: advice.text };
89
96
  }
90
97
  }
91
98
 
@@ -117,7 +124,11 @@ function bkitGuardrails(payload) {
117
124
  payload.tool_name == null &&
118
125
  payload.tool_input == null
119
126
  ) {
120
- return decideShell(payload.command, hookDirs(payload));
127
+ return decideShell(
128
+ payload.command,
129
+ hookContext(payload),
130
+ payload.session_id || payload.conversation_id,
131
+ );
121
132
  }
122
133
 
123
134
  // preToolUse Read/TabRead: { tool_name, tool_input: { path|file_path|target_file|... } }
@@ -1,19 +1,19 @@
1
1
  #!/usr/bin/env bash
2
2
  # bkit-preflight.sh — Cursor Cloud sessionStart hook (failClosed: true)
3
3
  #
4
- # Validates Linear issue state before any background/cloud session does bkit
4
+ # Validates tracker issue state before any background/cloud session does bkit
5
5
  # work. Refuses the session if the issue isn't approved for automation.
6
6
  #
7
7
  # Trigger: is_background_agent === true (received via stdin JSON).
8
- # Guards: `bkit:auto` label present; issue state not in {Cancelled, Done}.
9
- # Setup: See `.bkit/README.md` § Linear setup.
8
+ # Guards: `bkit:auto` label present; issue state not terminal by category.
9
+ # Setup: See `.bkit/README.md` for the configured tracker.
10
10
  #
11
11
  # Cursor honours non-zero exit as a hard stop (failClosed: true) — non-zero
12
12
  # blocks the session before the agent starts. Failures are also surfaced via
13
13
  # `additional_context` so the user sees the reason.
14
14
  #
15
- # bkit generates the managed block at install: the Linear guard and the rules-read
16
- # advisory are shared with the Claude hook (bkit's `hooks/preflight-linear.sh` and
15
+ # bkit generates the managed block at install: the tracker guard and the rules-read
16
+ # advisory are shared with the Claude hook (bkit's `hooks/preflight-tracker.sh` and
17
17
  # `hooks/preflight-rules.sh`); the trigger, the runtime marker and the output shape
18
18
  # below are Cursor's own.
19
19
 
@@ -29,7 +29,7 @@ INPUT=$(cat)
29
29
 
30
30
  # emit_context — Cursor sessionStart expects ONE JSON document { additional_context: ... }
31
31
  # on stdout. Each call accumulates its string; the EXIT trap writes the document once, so
32
- # the advisory and the Linear guard result ride one document. Defined above the bail so an
32
+ # the advisory and the tracker guard result ride one document. Defined above the bail so an
33
33
  # IDE session gets the advisory too, and built with no python3: failClosed:true blocks the
34
34
  # session on a non-zero exit, and an IDE session may not have python3 at all.
35
35
  # (Claude variant: wraps in { hookSpecificOutput: { hookEventName, additionalContext } }.)
@@ -73,7 +73,7 @@ trap bkit_write_document EXIT
73
73
  # IDE session bailout — grep only, no python3 on the skip path (failClosed:true in
74
74
  # .cursor/hooks.json blocks the session if this exits non-zero). Background-agent
75
75
  # sessions run inside the bkit Dockerfile, where python3 is present for the code below.
76
- # (Claude variant: uses empty LINEAR_ISSUE_ID env var as the proxy.)
76
+ # (Claude variant: uses the issue env vars as the proxy.)
77
77
  if ! printf '%s' "$INPUT" | grep -q '"is_background_agent"[[:space:]]*:[[:space:]]*true'; then
78
78
  exit 0
79
79
  fi
@@ -93,6 +93,6 @@ fi
93
93
  # pre-installed via .cursor/Dockerfile, so the laptop-side brew check makes no sense here.
94
94
  # (Claude variant: validates required CLIs are on PATH; missing → HARD STOP with brew install hint.)
95
95
 
96
- # {{BKIT_PART preflight-linear.sh}}
96
+ # {{BKIT_PART preflight-tracker.sh}}
97
97
 
98
98
  # <!-- bkit:end -->
@@ -56,6 +56,10 @@ import * as path from "node:path";
56
56
  // The terminal tool (`shell` in v2, `bash` before v2) is NOT in this list.
57
57
  const EDIT_TOOLS = new Set(["write", "edit", "patch", "apply_patch"]);
58
58
 
59
+ // The plugin process outlives a tool call, so a deny whose state file cannot be written is
60
+ // remembered in process and the retry passes.
61
+ const GATEGUARD_PROCESS_PERSISTS = true;
62
+
59
63
  // {{BKIT_PART gateguard-engine.js}}
60
64
 
61
65
  // Pure: takes the tool name, the already-extracted file path, and the session id
@@ -183,12 +187,18 @@ function advisoryFor(tool, targets, sessionID, isNewFile) {
183
187
  const mode = process.env.BKIT_GATEGUARD;
184
188
  if (mode === "off" || mode === "deny") return null;
185
189
  if (!EDIT_TOOLS.has(tool)) return null;
186
- const contexts = [];
190
+ // Every target is prepared (nothing recorded); only complete blocks inside the OpenCode
191
+ // budget are shown and acknowledged. Alias spellings of one file share one identity.
192
+ const blocks = [];
193
+ const seen = new Set();
187
194
  for (const target of targets) {
188
- const result = firstTouchAdvice(target.file, sessionID, target.isNew ?? isNewFile);
189
- if (result) contexts.push(result.context);
195
+ const prepared = prepareAdvice(target.file, sessionID, target.isNew ?? isNewFile);
196
+ if (!prepared || seen.has(prepared.key)) continue;
197
+ seen.add(prepared.key);
198
+ blocks.push(prepared);
190
199
  }
191
- return contexts.length > 0 ? contexts.join("\n\n") : null;
200
+ const delivered = deliverAdvice(blocks, ADVICE_BUDGETS.opencode, true);
201
+ return delivered ? delivered.context : null;
192
202
  }
193
203
 
194
204
  /** OpenCode 1.x before hook: `(input, output)`, tool args on `output.args`. */
@@ -0,0 +1,114 @@
1
+ // bkit-guardrails.js — bkit shell deny tier for opencode.
2
+ //
3
+ // Fires before every terminal command (`shell` in v2, `bash` before v2) and refuses the
4
+ // commands the other hosts' guardrails hooks refuse: a git force push, `rm -rf` of a
5
+ // filesystem root, `chmod -R 777 /`. The command is read by the same quote-aware parser
6
+ // as every other host (bkit's `core/hooks/guardrails-shell.js` and `guardrails-deny.js`),
7
+ // so a wrapper (`env -u FOO`, `timeout 30`, `nice -n 5`) does not hide the program, and a
8
+ // quoted sentence that only names a dangerous command is not refused.
9
+ //
10
+ // SCOPE — the deny tier only. The ask, secret and fetch tiers stay with opencode's own
11
+ // `permission.bash` map in `.opencode/opencode.json`.
12
+ //
13
+ // CONTRACT — do not regress:
14
+ // - REFUSE BY THROWING: the before-execute hook is block-or-allow (return = allow,
15
+ // throw = block); the thrown message is the reason the model reads.
16
+ // - FAIL OPEN: every other error is swallowed and the command runs.
17
+ //
18
+ // OWNERSHIP: everything between the markers below is bkit-managed and is overwritten on
19
+ // every `bkit install` / `bkit upgrade`. It is a pure decision engine only — no client
20
+ // calls, no throw — so it composes with your own checks in the exported plugin that
21
+ // follows the managed block.
22
+
23
+ // bkit:start
24
+
25
+ // {{BKIT_MANAGED_MARKER}}
26
+
27
+ import * as fs from "node:fs";
28
+ import * as os from "node:os";
29
+ import * as path from "node:path";
30
+
31
+ // opencode terminal tool names: `shell` in v2, `bash` before v2.
32
+ const SHELL_TOOLS = new Set(["shell", "bash"]);
33
+
34
+ // {{BKIT_PART gateguard-engine.js}}
35
+
36
+ // {{BKIT_PART guardrails-shell.js}}
37
+
38
+ // {{BKIT_PART guardrails-deny.js}}
39
+
40
+ /**
41
+ * Pure: takes the tool name and its arguments; returns the refusal reason for a command
42
+ * the deny tier refuses, or null.
43
+ */
44
+ function bkitGuardrails(toolName, args) {
45
+ if (!SHELL_TOOLS.has(toolName)) return null;
46
+ const cmd = args && typeof args === "object" ? args.command : undefined;
47
+ if (typeof cmd !== "string") return null;
48
+ const c = cmd.trim();
49
+ if (!c) return null;
50
+ const denied = denyRule(shellCommands(c));
51
+ if (!denied) return null;
52
+ return composeAdvice({ tier: "deny", ...denied }, "opencode", ADVICE_BUDGETS.opencode, {
53
+ command: c,
54
+ }).text;
55
+ }
56
+
57
+ // bkit:end
58
+
59
+ // ---------------------------------------------------------------------------
60
+ // Driver — the one export shape OpenCode 1.x and 2.0 both load.
61
+ //
62
+ // - OpenCode 2.0 reads the default export's `id` and `setup()` and registers
63
+ // `ctx.tool.hook("execute.before", …)`. The event carries the tool name and arguments
64
+ // as `event.tool` / `event.input`.
65
+ // - OpenCode 1.18.29+ calls the default export's `server()` and uses the returned
66
+ // `"tool.execute.before"` hook, whose arguments are `(input, output)`, tool args on
67
+ // `output.args`.
68
+ //
69
+ // The file imports NOTHING from `@opencode/plugin`: that package only exists on 2.0, and
70
+ // importing it would break the module load on 1.x.
71
+ // ---------------------------------------------------------------------------
72
+
73
+ /** Marks this plugin's own refusal, so fail-open swallows every other error. */
74
+ class BkitGuardrailsDeny extends Error {}
75
+
76
+ function isDenyThrow(err) {
77
+ return err instanceof BkitGuardrailsDeny;
78
+ }
79
+
80
+ /** Throws the refusal for a denied command; returns for every other command. */
81
+ function refuseDenied(tool, args) {
82
+ const reason = bkitGuardrails(tool, args);
83
+ if (reason) throw new BkitGuardrailsDeny(reason);
84
+ }
85
+
86
+ /** OpenCode 1.x before hook: `(input, output)`, tool args on `output.args`. */
87
+ async function bkitGuardrailsBeforeV1(hookInput, output) {
88
+ try {
89
+ refuseDenied(hookInput?.tool, output?.args);
90
+ } catch (err) {
91
+ if (isDenyThrow(err)) throw err;
92
+ }
93
+ }
94
+
95
+ /** OpenCode 2.0 before hook: one event, tool args on `event.input`. */
96
+ async function bkitGuardrailsBeforeV2(event) {
97
+ try {
98
+ refuseDenied(event?.tool, event?.input);
99
+ } catch (err) {
100
+ if (isDenyThrow(err)) throw err;
101
+ }
102
+ }
103
+
104
+ const bkitGuardrailsPlugin = {
105
+ id: "bkit-guardrails",
106
+ async setup(ctx) {
107
+ await ctx.tool.hook("execute.before", bkitGuardrailsBeforeV2);
108
+ },
109
+ async server() {
110
+ return { "tool.execute.before": bkitGuardrailsBeforeV1 };
111
+ },
112
+ };
113
+
114
+ export default bkitGuardrailsPlugin;
@@ -2,7 +2,7 @@
2
2
 
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
- <!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. -->
5
+ <!-- Note: @bkit-audit-generate fills this template. The report lives at `docs/audits/{YYYYMM}/{slug}.md`, where `{YYYYMM}` is the UTC month of the run and `{slug}` is this file's name without `bkit-audit-` and `.md`. **If** that month already has `{slug}.md` or `{slug}-{TIMESTAMP}.md` → write `{slug}-{TIMESTAMP}.md`, where `{TIMESTAMP}` is the output of `date -u +%Y%m%dT%H%M%SZ`. NEVER overwrite an earlier report. The report is stamped with a `bkit:anchor` block that records the audited commit (`baseSha`) and branch (`baseRef`). NEVER write or edit that block by hand. When you edit this template, follow `.bkit/authoring.md` § Doc Templates. -->
6
6
 
7
7
  # Accessibility Audit
8
8