@cbartens/bkit 6.1.1 → 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 (313) 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 +42 -32
  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 +97 -36
  15. package/.bkit/core/.bkit/templates.md +162 -34
  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 +89 -37
  64. package/.bkit/core/engine/checks/after/index.ts +15 -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 +64 -11
  74. package/.bkit/core/engine/commands/ci/push-gate.ts +101 -43
  75. package/.bkit/core/engine/commands/install/install.ts +28 -25
  76. package/.bkit/core/engine/commands/install/uninstall.ts +42 -30
  77. package/.bkit/core/engine/commands/install/upgrade.ts +14 -2
  78. package/.bkit/core/engine/commands/land.ts +2 -3
  79. package/.bkit/core/engine/commands/lib.ts +394 -39
  80. package/.bkit/core/engine/commands/registry.ts +1 -1
  81. package/.bkit/core/engine/commands/workflow/branches.ts +351 -78
  82. package/.bkit/core/engine/commands/workflow/challenge.ts +63 -14
  83. package/.bkit/core/engine/commands/workflow/context.ts +71 -10
  84. package/.bkit/core/engine/commands/workflow/counters.ts +298 -23
  85. package/.bkit/core/engine/commands/workflow/decisions.ts +260 -125
  86. package/.bkit/core/engine/commands/workflow/disk.ts +2 -1
  87. package/.bkit/core/engine/commands/workflow/feature-base.ts +66 -0
  88. package/.bkit/core/engine/commands/workflow/issues.ts +312 -17
  89. package/.bkit/core/engine/commands/workflow/junit.ts +204 -0
  90. package/.bkit/core/engine/commands/workflow/ledgers.ts +904 -99
  91. package/.bkit/core/engine/commands/workflow/locks.ts +186 -29
  92. package/.bkit/core/engine/commands/workflow/loops.ts +87 -0
  93. package/.bkit/core/engine/commands/workflow/open-decision.ts +251 -0
  94. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +8 -0
  95. package/.bkit/core/engine/commands/workflow/plans.ts +1 -1
  96. package/.bkit/core/engine/commands/workflow/prs.ts +311 -16
  97. package/.bkit/core/engine/commands/workflow/repo.ts +1 -1
  98. package/.bkit/core/engine/commands/workflow/run-facts.ts +6 -0
  99. package/.bkit/core/engine/commands/workflow/runs.ts +877 -174
  100. package/.bkit/core/engine/commands/workflow/runtime.ts +12 -4
  101. package/.bkit/core/engine/commands/workflow/status.ts +324 -11
  102. package/.bkit/core/engine/commands/workflow/step-table.ts +41 -15
  103. package/.bkit/core/engine/commands/workflow/steps.ts +604 -29
  104. package/.bkit/core/engine/commands/workflow/summary-findings.ts +1 -1
  105. package/.bkit/core/engine/commands/workflow/summary.ts +314 -8
  106. package/.bkit/core/engine/commands/workflow/tasks.ts +400 -27
  107. package/.bkit/core/engine/commands/workflow/tests-base.ts +319 -0
  108. package/.bkit/core/engine/commands/workflow/tests-changed.ts +138 -74
  109. package/.bkit/core/engine/commands/workflow/tests-jump.ts +93 -0
  110. package/.bkit/core/engine/commands/workflow/tests.ts +815 -182
  111. package/.bkit/core/engine/commands/workflow/tracker.ts +1134 -137
  112. package/.bkit/core/engine/commands/workflow/workflows.ts +100 -72
  113. package/.bkit/core/engine/commands/workflow/worktrees.ts +421 -57
  114. package/.bkit/core/engine/install/cloud-env.ts +38 -10
  115. package/.bkit/core/engine/install/managed-block.ts +105 -0
  116. package/.bkit/core/engine/install/manifest.ts +7 -1
  117. package/.bkit/core/engine/install/modules/claude.ts +6 -2
  118. package/.bkit/core/engine/install/modules/cloud.ts +84 -95
  119. package/.bkit/core/engine/install/modules/codex.ts +10 -2
  120. package/.bkit/core/engine/install/modules/core.ts +148 -14
  121. package/.bkit/core/engine/install/modules/opencode.ts +18 -23
  122. package/.bkit/core/engine/install/network-allowlist.ts +8 -3
  123. package/.bkit/core/engine/install/project-docs.ts +650 -0
  124. package/.bkit/core/engine/install/template-copies.ts +58 -5
  125. package/.bkit/core/engine/install/write.ts +128 -7
  126. package/.bkit/core/engine/ledgers/journal.ts +18 -10
  127. package/.bkit/core/engine/ledgers/migrate.ts +20 -8
  128. package/.bkit/core/engine/ledgers/status.ts +604 -8
  129. package/.bkit/core/engine/ledgers/telemetry.ts +115 -13
  130. package/.bkit/core/engine/render/trackers.ts +3 -1
  131. package/.bkit/core/engine/shared/package-manager.ts +7 -3
  132. package/.bkit/core/engine/shared/settings.ts +12 -1
  133. package/.bkit/core/engine/shared/text.ts +14 -0
  134. package/.bkit/core/engine/tools/instructions-sources.ts +1 -0
  135. package/.bkit/core/engine/tools/instructions.ts +116 -20
  136. package/.bkit/core/hooks/antigravity-hook.js +20 -4
  137. package/.bkit/core/hooks/gateguard-edit-payload.js +8 -5
  138. package/.bkit/core/hooks/gateguard-engine.js +249 -23
  139. package/.bkit/core/hooks/guardrails-deny.js +167 -0
  140. package/.bkit/core/hooks/guardrails-read.js +3 -3
  141. package/.bkit/core/hooks/guardrails-shell.js +1122 -167
  142. package/.bkit/core/hooks/guardrails-tiers.js +247 -176
  143. package/.bkit/core/hooks/preflight-tracker.sh +219 -0
  144. package/.bkit/core/prompts/bkit-audit-generate.md +23 -6
  145. package/.bkit/core/prompts/bkit-build-challenge-1.md +5 -4
  146. package/.bkit/core/prompts/bkit-build-challenge-2.md +6 -5
  147. package/.bkit/core/prompts/bkit-build-install-skills.md +2 -2
  148. package/.bkit/core/prompts/bkit-build-plan-convert.md +21 -7
  149. package/.bkit/core/prompts/bkit-build-plan-current.md +5 -4
  150. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +22 -17
  151. package/.bkit/core/prompts/bkit-build-plan-tasks.md +16 -12
  152. package/.bkit/core/prompts/bkit-build-plan-tests.md +14 -10
  153. package/.bkit/core/prompts/bkit-build-plan-verify.md +21 -8
  154. package/.bkit/core/prompts/bkit-debug-abort-handover.md +10 -5
  155. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +22 -6
  156. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +19 -3
  157. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +22 -6
  158. package/.bkit/core/prompts/bkit-debug-failure-soak.md +10 -7
  159. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +3 -3
  160. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +4 -4
  161. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +3 -3
  162. package/.bkit/core/prompts/bkit-design-generate.md +6 -4
  163. package/.bkit/core/prompts/bkit-design-organise.md +4 -3
  164. package/.bkit/core/prompts/bkit-design-review-1.md +5 -4
  165. package/.bkit/core/prompts/bkit-design-review-2.md +6 -5
  166. package/.bkit/core/prompts/bkit-design-spike.md +4 -3
  167. package/.bkit/core/prompts/bkit-design-update.md +6 -4
  168. package/.bkit/core/prompts/bkit-plan-generate.md +35 -14
  169. package/.bkit/core/prompts/bkit-plan-review-1.md +9 -7
  170. package/.bkit/core/prompts/bkit-plan-review-2.md +9 -7
  171. package/.bkit/core/prompts/bkit-plan-scope-check.md +8 -6
  172. package/.bkit/core/prompts/bkit-plan-update.md +22 -8
  173. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +11 -8
  174. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +9 -5
  175. package/.bkit/core/prompts/bkit-ship-update-docs.md +26 -4
  176. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +3 -3
  177. package/.bkit/core/prompts/bkit-utility-update-decisions.md +10 -7
  178. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +8 -5
  179. package/.bkit/core/prompts/bkit-utility-update-documentation.md +31 -7
  180. package/.bkit/core/prompts/bkit-utility-update-failures.md +8 -5
  181. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +10 -7
  182. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +4 -4
  183. package/.bkit/core/prompts/bkit-utility-update-tracker.md +4 -4
  184. package/.bkit/core/workflows/bkit-auto.md +23 -11
  185. package/.bkit/core/workflows/bkit-build.md +331 -100
  186. package/.bkit/core/workflows/bkit-debug.md +135 -64
  187. package/.bkit/core/workflows/bkit-design.md +58 -32
  188. package/.bkit/core/workflows/bkit-plan.md +73 -45
  189. package/.bkit/core/workflows/bkit-ship.md +233 -167
  190. package/.bkit/shared/.agents/plugins/bkit/hooks.json +1 -1
  191. package/.bkit/shared/.bkit/.env.example +5 -0
  192. package/.bkit/shared/.claude/bkit-cloud.md +7 -7
  193. package/.bkit/shared/.claude/settings.json +5 -1
  194. package/.bkit/shared/.cursor/bkit-cloud.md +1 -1
  195. package/.bkit/shared/.cursor/hooks.json +1 -1
  196. package/.bkit/shared/.opencode/opencode.json +11 -2
  197. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +27 -0
  198. package/.bkit/templates/.cursor/Dockerfile +7 -7
  199. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +1 -1
  200. package/.bkit/templates/.github/dependabot.yml +5 -0
  201. package/.bkit/templates/.github/renovate.json5 +5 -3
  202. package/.bkit/templates/.github/workflows/bkit-ci.yml +11 -11
  203. package/.bkit/templates/.github/workflows/bkit-cloud.yml +525 -161
  204. package/.bkit/templates/.github/workflows/bkit-renovate.yml +2 -2
  205. package/.bkit/templates/.husky/pre-push +123 -6
  206. package/.bkit/templates/context/bkit-serena.md +1 -1
  207. package/.bkit/templates/docs/architecture.md +98 -0
  208. package/.bkit/templates/docs/capabilities.md +33 -37
  209. package/.bkit/templates/docs/components.md +142 -0
  210. package/.bkit/templates/docs/data-schema.md +87 -0
  211. package/.bkit/{shared → templates}/docs/deployments.md +128 -142
  212. package/.bkit/templates/docs/design.md +117 -0
  213. package/.bkit/templates/docs/noise.md +54 -0
  214. package/.bkit/templates/docs/observability.md +99 -0
  215. package/.bkit/templates/docs/security.md +137 -0
  216. package/.bkit/templates/docs/setup.md +93 -0
  217. package/.bkit/templates/docs/technology.md +70 -0
  218. package/.bkit/{shared → templates}/docs/testing.md +200 -87
  219. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +511 -103
  220. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +228 -35
  221. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +270 -2
  222. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  223. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +92 -63
  224. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +59 -11
  225. package/.bkit/templates/slop-scan.config.json +2 -0
  226. package/CHANGELOG.md +64 -0
  227. package/DETAILS.md +24 -19
  228. package/README.md +1 -1
  229. package/dist/checks/after/auth.js +114 -46
  230. package/dist/checks/after/github.js +77 -35
  231. package/dist/checks/after/index.js +12 -3
  232. package/dist/checks/after/tools.js +224 -1
  233. package/dist/checks/before/files.js +59 -1
  234. package/dist/checks/before/index.js +7 -1
  235. package/dist/checks/status-holes.js +20 -21
  236. package/dist/checks/tips/catalogue.js +99 -10
  237. package/dist/checks/tips/detect.js +35 -3
  238. package/dist/checks/tips/index.js +1 -1
  239. package/dist/cli.js +13 -13
  240. package/dist/commands/ci/ci.js +56 -12
  241. package/dist/commands/ci/push-gate.js +79 -44
  242. package/dist/commands/install/install.js +23 -22
  243. package/dist/commands/install/uninstall.js +36 -30
  244. package/dist/commands/install/upgrade.js +10 -2
  245. package/dist/commands/land.js +2 -3
  246. package/dist/commands/lib.js +323 -25
  247. package/dist/commands/workflow/branches.js +312 -72
  248. package/dist/commands/workflow/challenge.js +66 -13
  249. package/dist/commands/workflow/context.js +46 -10
  250. package/dist/commands/workflow/counters.js +231 -23
  251. package/dist/commands/workflow/decisions.js +221 -106
  252. package/dist/commands/workflow/disk.js +2 -1
  253. package/dist/commands/workflow/feature-base.js +60 -0
  254. package/dist/commands/workflow/issues.js +243 -15
  255. package/dist/commands/workflow/junit.js +137 -0
  256. package/dist/commands/workflow/ledgers.js +726 -112
  257. package/dist/commands/workflow/locks.js +150 -29
  258. package/dist/commands/workflow/loops.js +67 -0
  259. package/dist/commands/workflow/open-decision.js +199 -0
  260. package/dist/commands/workflow/plan-blocks.js +6 -0
  261. package/dist/commands/workflow/plans.js +1 -1
  262. package/dist/commands/workflow/prs.js +272 -16
  263. package/dist/commands/workflow/repo.js +1 -1
  264. package/dist/commands/workflow/run-facts.js +6 -0
  265. package/dist/commands/workflow/runs.js +747 -155
  266. package/dist/commands/workflow/runtime.js +8 -4
  267. package/dist/commands/workflow/status.js +259 -13
  268. package/dist/commands/workflow/step-table.js +41 -15
  269. package/dist/commands/workflow/steps.js +530 -26
  270. package/dist/commands/workflow/summary-findings.js +1 -1
  271. package/dist/commands/workflow/summary.js +289 -8
  272. package/dist/commands/workflow/tasks.js +294 -27
  273. package/dist/commands/workflow/tests-base.js +266 -0
  274. package/dist/commands/workflow/tests-changed.js +130 -56
  275. package/dist/commands/workflow/tests-jump.js +77 -0
  276. package/dist/commands/workflow/tests.js +608 -131
  277. package/dist/commands/workflow/tracker.js +920 -112
  278. package/dist/commands/workflow/workflows.js +80 -59
  279. package/dist/commands/workflow/worktrees.js +387 -58
  280. package/dist/install/cloud-env.js +32 -10
  281. package/dist/install/managed-block.js +101 -0
  282. package/dist/install/manifest.js +7 -1
  283. package/dist/install/modules/claude.js +6 -2
  284. package/dist/install/modules/cloud.js +73 -86
  285. package/dist/install/modules/codex.js +9 -2
  286. package/dist/install/modules/core.js +133 -14
  287. package/dist/install/modules/opencode.js +18 -23
  288. package/dist/install/network-allowlist.js +8 -3
  289. package/dist/install/project-docs.js +551 -0
  290. package/dist/install/template-copies.js +55 -5
  291. package/dist/install/write.js +117 -5
  292. package/dist/ledgers/journal.js +10 -8
  293. package/dist/ledgers/migrate.js +20 -9
  294. package/dist/ledgers/status.js +461 -8
  295. package/dist/ledgers/telemetry.js +71 -13
  296. package/dist/render/trackers.js +3 -1
  297. package/dist/shared/package-manager.js +7 -2
  298. package/dist/shared/settings.js +8 -0
  299. package/dist/shared/text.js +13 -0
  300. package/dist/tools/instructions-sources.js +1 -0
  301. package/dist/tools/instructions.js +97 -24
  302. package/package.json +22 -15
  303. package/.bkit/core/hooks/preflight-linear.sh +0 -73
  304. package/.bkit/shared/docs/architecture.md +0 -16
  305. package/.bkit/shared/docs/data-schema.md +0 -16
  306. package/.bkit/shared/docs/design.md +0 -38
  307. package/.bkit/shared/docs/noise.md +0 -20
  308. package/.bkit/shared/docs/observability.md +0 -22
  309. package/.bkit/shared/docs/security.md +0 -62
  310. package/.bkit/shared/docs/setup.md +0 -52
  311. package/.bkit/shared/docs/technology.md +0 -15
  312. /package/.bkit/templates/{.lintstagedrc.json → lintstagedrc.example.json} +0 -0
  313. /package/.bkit/templates/{.prettierignore → prettierignore.example} +0 -0
@@ -24,7 +24,7 @@
24
24
  | Codex | additive (opt-in) | `.codex/agents/` (TOML) | none — skills (below) | none (`openai` = reserved built-in id) | `.codex/hooks/bkit-gateguard.cjs` + `.codex/hooks/bkit-guardrails.cjs` + `.codex/hooks/bkit-readguard.cjs` + `.codex/hooks/bkit-rules.cjs` (PreToolUse `apply_patch` / `Bash`, PreCompact, via `.codex/hooks.json`) | `bkit install --codex` |
25
25
  | Antigravity | additive (opt-in) | `.agents/plugins/bkit/agents/` | none — skills (plugin, below) | `GEMINI.md` (workspace rule) | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` + `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` + `.agents/plugins/bkit/hooks/bkit-readguard.cjs` + `.agents/plugins/bkit/hooks/bkit-rules.cjs` (PreToolUse `write_to_file` / `replace_file_content` / `view_file` / `run_command`, via `.agents/plugins/bkit/hooks.json`) | `bkit install --antigravity` |
26
26
  | Cursor | derived | `.cursor/agents/` | `.cursor/commands/` | `.cursor/settings.json` + `.cursor/environment.json` + `.cursor/Dockerfile` (templates, `.bkit/templates.md`) | `.cursor/hooks/` (registered in `.cursor/hooks.json`) | `bkit install --cursor` |
27
- | OpenCode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` + `.opencode/plugin/bkit-readguard.js` + `.opencode/plugin/bkit-rules.js` (tool execute hooks) | `bkit install --opencode=<provider>` |
27
+ | OpenCode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` + `.opencode/plugin/bkit-guardrails.js` + `.opencode/plugin/bkit-readguard.js` + `.opencode/plugin/bkit-rules.js` (tool execute hooks) | `bkit install --opencode=<provider>` |
28
28
 
29
29
  **Two axes — host != provider.** A **host** is the program that reads what bkit writes, and its dir identifies it (`.claude/`, `.codex/`, `.cursor/`, `.opencode/`). A **provider** is the gateway the tokens are bought through. Model IDs differ per provider, so `prompts.md` § Models has one column per provider, and a shared provider gets one column, never two. Thinking depth differs per host, because the host's config format sets the field name and the ladder (`effort:` on claude / cursor, a `variant:` field on OpenCode, `model_reasoning_effort` on codex), so § Effort has one column per host. Neither table grows as hosts x providers.
30
30
 
@@ -44,7 +44,7 @@
44
44
  | Cursor | `cursor` | Cursor subscription covers its whole catalog |
45
45
  | OpenCode | pick one: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | overflow host — metered BYO key, runs when subscription usage is spent |
46
46
 
47
- A host with a subscription has a pinned provider and a flag that takes no value (`--claude`, `--codex`). A bring-your-own-key host has a pluggable provider, and its flag names the provider (`--opencode=<provider>`). A per-model deviation goes in the consumer's `## Model Overrides` below `bkit:end`. There is no provider override.
47
+ A host with a subscription has a pinned provider and a flag that takes no value (`--claude`, `--codex`). A bring-your-own-key host has a pluggable provider, and its flag names the provider (`--opencode=<provider>`). A per-model deviation goes in the consumer's `## Model Overrides` below `bkit:end`. No provider override exists.
48
48
 
49
49
  ### Codex CLI — three deviations
50
50
 
@@ -57,7 +57,7 @@ A host with a subscription has a pinned provider and a flag that takes no value
57
57
 
58
58
  > **GateGuard needs the `.codex/` layer trusted.** Codex loads project-local hooks only once that layer is trusted. Until then the hook is installed but never fires, so its presence proves nothing. The same holds for `bkit-guardrails.cjs`.
59
59
  >
60
- > **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it: an ask is recorded as an error, and the call proceeds, so `bkit-guardrails.cjs` blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`. The gate fires and informs, but it cannot stop the command. Every ask-tier command is already prohibited in all five workflow headers, so no bkit workflow reaches one. `.bkit/core/engine/install/modules/index.integration.test.ts` asserts this.
60
+ > **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it: an ask is recorded as an error, and the call proceeds, so `bkit-guardrails.cjs` blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`. The gate fires and informs, but it cannot stop the command. Every ask-tier command is already prohibited in all five workflow headers, so no bkit workflow reaches one. The exception is `bkit tests jump`, which needs the human's approval: Codex denies it, and the agent asks the human to run it in their own terminal. `.bkit/core/engine/install/modules/index.integration.test.ts` asserts this.
61
61
 
62
62
  ### Antigravity — installs as a workspace plugin
63
63
 
@@ -76,7 +76,7 @@ A host with a subscription has a pinned provider and a flag that takes no value
76
76
 
77
77
  **Cheap models inside an IDE — no extension needed.** A host is its dir, not the window its process runs in. `bkit install --claude --cursor --opencode=openrouter`, with OpenCode in the IDE's integrated terminal, runs every agent pin, GateGuard and the full workflow on OpenRouter while you edit in Cursor. This is the supported path when the Claude subscription is spent.
78
78
 
79
- > **Curated-column status (complete).** All four allowlisted providers (`openrouter`, `ollama`, `opencode-zen`, `opencode-go`) ship curated per-agent model pins in `prompts.md` § Models, so an install is ready to run. Both OpenAI-compatible providers and both OpenCode gateways are curated after a live catalog probe and a per-model tool-calling smoke test (a `tools:` chat/completions round-trip emitting `tool_calls`; `/models` alone != proof). The OpenCode catalogs come from models.dev, not `/zen/v1/models`: that REST endpoint returns Zen only and cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`, …). models.dev is the source of truth (`opencode` = Zen, `opencode-go` = Go). `opencode-go` is curated from the models.dev/Go endpoint. Prefer pins within the Go 5h window. `opencode-zen` is existence-validated via models.dev. § Provider models has the live-probe recipe and the tier rationale.
79
+ > **Curated-column status (complete).** All four allowlisted providers (`openrouter`, `ollama`, `opencode-zen`, `opencode-go`) ship curated per-agent model pins in `prompts.md` § Models, so an install is ready to run. Both OpenAI-compatible providers and both OpenCode gateways are curated after a live catalog probe, which confirms each model exists on the provider. The per-model tool-calling smoke test (a `tools:` chat/completions round-trip emitting `tool_calls`; `/models` alone != proof) has not been run on the current pins (`prompts.md` § Live model-ID verification). The OpenCode catalogs come from models.dev, not `/zen/v1/models`: that REST endpoint returns Zen only and cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`, …). models.dev is the source of truth (`opencode` = Zen, `opencode-go` = Go). `opencode-go` is curated from the models.dev/Go endpoint. Prefer pins within the Go 5h window. `opencode-zen` is existence-validated via models.dev. § Provider models has the live-probe recipe and the tier rationale.
80
80
 
81
81
  **Additive multi-provider install:** `bkit install --opencode=<provider>` is additive: a second provider adds its block to `opencode.json` and keeps the first. Agent frontmatter (`model:`) re-renders to the last-installed (active) provider, and the other blocks stay for interactive switching and overrides. The installed providers go in `bkit.providers.opencode.installed: string[]` in `package.json`, and the active one in `bkit.providers.opencode.default`. `bkit status` lists them all, marks the active one, and prints the `model:` pins read from `.opencode/agents/*.md`. `bkit doctor` checks all credentials. `bkit uninstall --opencode=<provider>` removes one provider surgically, taking its block and its array entry. When it removes the active provider, the first remaining provider becomes active, and agents and commands re-render to its pins, so `bkit check` stays green. A bare `bkit uninstall --opencode` tears down the entire OpenCode host.
82
82
 
@@ -148,7 +148,7 @@ The persistent variant is a `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgen
148
148
  | --- | --- | --- | --- | --- |
149
149
  | `name` | required | required | required | kebab-case, must match filename. Identical. |
150
150
  | `description` | required | required | required | Identical. |
151
- | `effort` | required (`low` / `medium` / `high` / `xhigh` / `max` — last two model-gated, Opus-only on current models) | emitted from the Cursor column of the effort table in `prompts.md` § Frontmatter Conventions (`applyT3`) | emitted as a separate `variant:` field | `applyOpencodeAgent` reads the § Effort OpenCode column and writes it to `variant:`, not as a `#`-suffix on the model, because 1.x keeps the suffix in its model id and fails lookup. The OpenCode column ceilings out, so `medium` / `high` / `xhigh` / `max`→`max` and `low`→`none`, then `clampOpencodeVariant` clamps that to what the pinned model exposes on the gateway (`prompts.md` § Effort). The ollama gateway omits `variant:` entirely: its provider builds models with no variants, so any variant there is a hard 2.0 error. |
151
+ | `effort` | required (`low` / `medium` / `high` / `xhigh` / `max` — last two model-gated; Opus and Sonnet accept `xhigh`) | emitted from the Cursor column of the effort table in `prompts.md` § Frontmatter Conventions (`applyT3`) | emitted as a separate `variant:` field | `applyOpencodeAgent` reads the § Effort OpenCode column and writes it to `variant:`, not as a `#`-suffix on the model, because 1.x keeps the suffix in its model id and fails lookup. The OpenCode column ceilings out, so `medium` / `high` / `xhigh` / `max`→`max` and `low`→`none`, then `clampOpencodeVariant` clamps that to what the pinned model exposes on the gateway (`prompts.md` § Effort). The ollama gateway omits `variant:` entirely: its provider builds models with no variants, so any variant there is a hard 2.0 error. |
152
152
  | `tools` | required (e.g. `[Read, Grep, Glob, Write, Edit, Bash, WebFetch, WebSearch]`) | supported (allowlist) + `disallowedTools` denylist | object map `{ <tool>: true }` | Identity mapping on Cursor (verified), not enforced by Cursor CLI 2026.10.01 (measured: a `tools: [Read]` subagent keeps `Shell` / `Write` / every MCP tool). OpenCode: built-ins lowercased; `mcp__<server>__<tool>` respelled `<server>_<tool>` (`mcp__serena__*` → `serena_*`). |
153
153
  | `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and OpenCode. |
154
154
  | `maxTurns` | required | not supported | not supported | Drop on Cursor and OpenCode. |
@@ -174,16 +174,16 @@ Cursor model assignment: § Models below. It is a per-agent lookup, not derived
174
174
 
175
175
  The pinned selections are canonical in `prompts.md` (§ Models `Cursor` column and § Orchestrators), not here. The Cursor set churns, so use the pull recipe below.
176
176
 
177
- > **Default install = first-party pool only.** The shipped Cursor pins are `cursor-grok-4.5-high` and `composer-2.5`, so workflows keep running when API credits are exhausted. API-pool models (Claude / GPT / Fable) are opt-in via `prompts.md` § Model Overrides, never default pins. To use Opus when you have API credits, paste the ready-to-use Opus override block in `prompts.md` § Model Overrides. It maps every Claude-opus-tier agent → `claude-opus-5-thinking-high`, and `/v0/models` has no Opus 5.5 ID. The Sonnet-tier override is `claude-sonnet-5-thinking-high` (Sonnet 5, not 5.5) or `gpt-5.6-sol-high`. Then run `bkit install --cursor`. The shipped sonnet cells stay on the first-party ceiling: `grok-4.5` lands 2.9 under the sonnet target at a quarter of Claude's cost per task. There is no `cursor-grok-4.7`.
177
+ > **Default install = first-party pool only.** The shipped Cursor pins are `cursor-grok-4.5-high` and `composer-2.5`, so workflows keep running when API credits are exhausted. API-pool models (Claude / GPT / Fable) are opt-in via `prompts.md` § Model Overrides, never default pins. To use Opus when you have API credits, paste the ready-to-use Opus override block in `prompts.md` § Model Overrides. It maps every Claude-opus-tier agent → `claude-opus-5-thinking-high`, and `/v0/models` has no Opus 5.5 ID. The Sonnet-tier override is `claude-sonnet-5-thinking-high` (Sonnet 5, not 5.5) or `gpt-5.6-sol-high`. Then run `bkit install --cursor`. The shipped sonnet cells stay on the first-party ceiling: `grok-4.5` lands 2.9 under the sonnet target at a quarter of Claude's cost per task. `cursor-grok-4.7` does not exist.
178
178
 
179
179
  Tier guidance:
180
180
 
181
181
  - **`composer-2.5`** ($) — default. Fast and cheap: build executors, utilities, and the `/build` and `/ship` orchestrators. First-party pool.
182
182
  - **`cursor-grok-4.5-high`** ($$) — default. Depth slots, synthesizers and parallel diversity (the design / plan / debug orchestrators and the former Opus-tier agents). First-party pool (Cursor and SpaceXAI), with Coding Agent Index parity with GPT-5.5 at a lower per-task cost. A `-fast` variant exists.
183
183
  - **`claude-opus-5-thinking-high`** ($$$) — override only. Deep review, audit and synthesis while API credits remain. `/v0/models` has Opus 5, not Opus 5.5 (`claude-opus-5-5` is the Claude pin). A `-fast` variant exists. It is on the API pool and burns credits, so pin it via § Model Overrides, never as a shipped default.
184
- - **`claude-sonnet-5-thinking-high`/`-xhigh`** ($$$) — override only. Sonnet 5 on the API pool. Not a shipped default. There is no Sonnet 5.5 ID.
184
+ - **`claude-sonnet-5-thinking-high`/`-xhigh`** ($$$) — override only. Sonnet 5 on the API pool. Not a shipped default. No Sonnet 5.5 ID exists.
185
185
  - **`gpt-5.*`** ($$$) — override only. An API-pool diversity hedge (`gpt-5.6-sol-high`, …). Not pinned.
186
- - **`claude-fable-5-thinking-high`/`-xhigh`** ($$$$) — override only. Fable 5. Available, but not adopted as a default (see `prompts.md` § Effort → Claude model mapping). There is no Fable 5.1 ID on `/v0/models`.
186
+ - **`claude-fable-5-thinking-high`/`-xhigh`** ($$$$) — override only. Fable 5. Available, but not adopted as a default (see `prompts.md` § Effort → Claude model mapping). `/v0/models` has no Fable 5.1 ID.
187
187
 
188
188
  Cloud Agents API: `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"`, with an agent-specific API key, because general keys can return HTTP 500 on `POST /v0/agents`. Verify before install, because Cursor models churn. The latest probe is in § Per-provider live model lookup. The build / ship orchestrators use `composer-2.5`.
189
189
 
@@ -267,10 +267,10 @@ Per-action gates on all five hosts, subagents included. This section is an overv
267
267
  <!-- prettier-ignore -->
268
268
  | Guard | Trigger | Effect | Enforcement |
269
269
  | --- | --- | --- | --- |
270
- | Destructive commands | Shell | deny: force-push (never `--force-with-lease`), `rm -rf` / `rm -fr` on `/`, `~`, `$HOME` or `${HOME}` (bare, `/`, `/*`; the hooks also catch `-Rf` and `-r -f`), `chmod -R 777 /`; ask: `git reset --hard`, forced `git clean`, whole-tree `git checkout` / `git restore`, `git rebase -i`, `git stash drop` / `git stash clear`, `git filter-branch`, `--no-verify`, publish, destructive `gh` | Claude / OpenCode permission rules; Codex / Antigravity / Cursor `bkit-guardrails` hook. Codex ask → advisory |
271
- | Secret files | Read tool; shell reads on Codex, Antigravity, Cursor | Read tool: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*`. Shell reads of any of them: ask on Antigravity and Cursor, advisory on Codex, not gated on Claude and OpenCode (§ Permissions / auto-approve) | Codex shell → advisory |
270
+ | Destructive commands | Shell | deny: force-push (never `--force-with-lease`), `rm -rf` / `rm -fr` on `/`, `~`, `$HOME` or `${HOME}` (bare, `/`, `/*`; the hooks also catch `-Rf`, `-r -f`, `//` and `/.`), `chmod -R 777 /` (the hooks: any world-writable mode, `0777`, `a+rwx`, `o+w`); ask: `git reset --hard`, forced `git clean`, whole-tree `git checkout` / `git restore`, `git rebase -i`, `git stash drop` / `git stash clear`, `git filter-branch`, `--no-verify`, publish, destructive `gh` | deny: the `bkit-guardrails` hook on all five hosts (a plugin on OpenCode), on the parsed command: wrappers (`env -u FOO`, `timeout 30`, `nice -n 5`, `doas`, `setsid`, `busybox`) do not hide the program, and words only inside quotes are not refused; Claude / OpenCode permission globs deny too. ask: Claude / OpenCode permission globs; Codex / Antigravity / Cursor hook. Codex ask → advisory |
271
+ | Secret files | Read tool; shell reads on Codex, Antigravity, Cursor | Read tool: deny a private-key file (Claude and OpenCode: `*.pem` / `*.p12` / `id_rsa`; Antigravity and Cursor: the key files of § Permissions / auto-approve, shell row), ask `.env` / `.env.*`. A shell command naming any of them: ask on Antigravity and Cursor; on Codex a command that prints or sends a private key's content is denied (configured to deny, not verified on a real Codex host) and an `.env` read is advisory; not gated on Claude and OpenCode (§ Permissions / auto-approve) | Codex shell → printing or sending a private key denied (not verified on a real host), `.env` advisory |
272
272
  | Network | `curl` / `wget`, fetch tool | ask unless host in allowlist (§ Network allowlist) | Advisory on Claude shell, Codex; Antigravity denies once, retry passes |
273
- | Shell-as-edit-channel | `sed -i`, redirect into a source file | Advisory: edit skips pre-edit gates | All hosts except OpenCode |
273
+ | Shell-as-edit-channel | A known writer (`sed -i`, `tee`, `cp` / `mv`, `prettier --write`, … — § GateGuard), redirect into a source file; script runners stay silent | Advisory: edit skips pre-edit gates | All hosts except OpenCode |
274
274
  | GateGuard | First edit per (session, agent, file) | Investigation checklist; gate-config path → fix-code advisory; new file → reuse nudge; `docs/**.md` → density advisory | Advisory; `BKIT_GATEGUARD=deny` denies first touch once |
275
275
  | ReadGuard | Repeat read of an unchanged range | Use-earlier-output note | Advisory, never blocks |
276
276
 
@@ -298,27 +298,41 @@ Per-action gates on all five hosts, subagents included. This section is an overv
298
298
  <!-- prettier-ignore -->
299
299
  | Part | Shared by | Holds |
300
300
  | --- | --- | --- |
301
- | `gateguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
301
+ | `gateguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `gateguard` and `guardrails` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice`; per-host `ADVICE_BUDGETS` and `composeAdvice`, the one function that writes every host's guardrails refusal and advice text |
302
302
  | `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
303
303
  | `readguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
304
304
  | `readguard-payload.js` | Claude, Codex, Antigravity, Cursor `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
305
305
  | `antigravity-hook.js` | Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
306
- | `guardrails-shell.js` | Claude, Codex, Antigravity, Cursor `guardrails` | shell parsing (`shellSegments`, `shellWords`, `commandWords`, `commandLines`: `sh -c` scripts, `$(…)`, backticks, `( … )`), curl / wget host allowlist (`.bkit/allowlist.json` located from `hookDirs(payload)`), shell-as-edit-channel detection (quote-aware redirects) |
307
- | `guardrails-tiers.js` | Codex, Antigravity, Cursor `guardrails` | git parsing (`parseGit`), deny + ask rules, `secretFileKind`, shell secret-read detection, `classifyShell` precedence |
308
- | `guardrails-read.js` | Antigravity, Cursor `guardrails` | `classifyRead` over `secretFileKind`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
309
- | `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
306
+ | `guardrails-shell.js` | Claude, Codex, Antigravity, Cursor, OpenCode `guardrails` | the quote-aware shell parser (`lexShell`, `shellCommands`): each simple command with its wrappers stripped (`env`, `timeout`, `nice`, `sudo`, `doas`, `setsid`, `busybox`, …) and a `function NAME` head skipped, its redirects and its `<` stdin file, plus the commands inside `sh -c` / `bash -c` scripts (the first operand after the options, so `bash -c -- '…'` too), `eval`'s words, an `env -S` string, a `find -exec` command, `$(…)`, backticks, `( … )`, `<(…)`, a heredoc or here-string fed to a shell, the literal output of `echo`, `printf` or `cat <<` piped into a shell, and the literal output of an `echo` / `printf` in `<(…)` given to a shell or `source`, to depth 3; text a shell reads from any other command (`curl … \| bash`) or from a computed word (`$GIT push`) is not judged; command text over 256 KiB is cut at the last whole UTF-8 character and the rest is not judged. `shellCommandText` turns a host's argv-array command into shell text, quoting each element, so `["bash", "-lc", "git push -f"]` is judged on its script. Also the curl / wget host allowlist (the URL hosts in the parsed curl / wget words, checked against `.bkit/allowlist.json` located from `hookContext(payload)`) and shell-as-edit-channel advice from `KNOWN_WRITERS` and `>` / `>>` redirects (`shellEditTargets`, `shellEditAdvisory`) |
307
+ | `guardrails-deny.js` | Claude, Codex, Antigravity, Cursor, OpenCode `guardrails` | the deny tier: git parsing (`parseGit`), `gitDenyRule`, `denyRule` |
308
+ | `guardrails-tiers.js` | Codex, Antigravity, Cursor `guardrails` | ask rules, `secretFileKind` over the one key-file rule `mayNameKeyFile`, shell secret-read detection, the Codex-only `bkit tests jump` deny and private-key exposure deny, `classifyShell` precedence; each driver passes its host name to `classifyShell` |
309
+ | `guardrails-read.js` | Antigravity, Cursor `guardrails` | `classifyRead` over `secretFileKind`: deny a private-key file (`mayNameKeyFile`), ask `.env` / `.env.*` (not `.env.example`) |
310
+ | `preflight-tracker.sh` | Claude, Cursor `preflight` | Tracker guard: GitHub (REST), Linear (GraphQL) and Jira (`bkit issues fetch`) key / issue checks, `bkit:auto` + terminal-by-category guards; a session with no issue id is unguarded; a non-digit `GITHUB_ISSUE_ID` or an unknown `bkit.tracker.default` fails |
310
311
  | `preflight-rules.sh` | Claude, Cursor `preflight` | the rules-read advisory sentence and its `emit_context` call, merged into the one SessionStart JSON document |
311
312
  | `session-rules-advisory.js` | Codex, Antigravity, OpenCode `rules` | the rules-read advisory sentence plus the once-per-session helper (`rulesReadAdviceOnce`, per-user OS-temp state, 24h GC) |
312
313
 
313
314
  Per host, outside the parts:
314
315
 
315
- - Claude `gateguard` / `guardrails`: the `require` and `hookSpecificOutput` driver. Guardrails is advisory-only.
316
+ - Claude `gateguard` / `guardrails`: the `require` and `hookSpecificOutput` driver. Guardrails refuses the deny tier with `permissionDecision: "deny"` and exits 0, because the `.claude/settings.json` registration ends in `|| true`, which swallows a non-zero exit. Its URL-host and edit checks are `additionalContext` advice, and it adds no ask or secret tier.
316
317
  - Codex: the `apply_patch` envelope parser, with the ask tier emitted as advisory.
317
318
  - Antigravity: the `antigravity-hook.js` envelope conversion and deny-once delivery, the `{ decision, reason }` driver, the `write_to_file` / `replace_file_content` edit tools (path `TargetFile`), and `view_file` and `run_command` (`CommandLine`).
318
319
  - Cursor: the `{ permission }` output, guardrails `Read|TabRead` path extraction, and gateguard workspace-relative path resolution.
319
320
  - OpenCode: an ES module with the `write` / `edit` / `patch` (`apply_patch`) vocabulary. It checks every `*** Add|Update|Delete File:` / `*** Move to:` target of a `patchText`, and deny mode blocks if any target is a first touch. It appends the checklist to the tool result in `execute.after` and throws from `execute.before` to block, because 2.0 exposes no pre-edit context hook, and stderr does not reach the model.
321
+ - OpenCode `guardrails`: refuses the deny tier by throwing `BkitGuardrailsDeny` from `execute.before` (`tool.execute.before` on 1.x) on the `shell` / `bash` tool, and lets the command run on any other error. Its ask, secret and fetch tiers stay in `permission.bash`, and it gives no edit advice.
320
322
  - `preflight`: the trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` and the `.bkit/.runtime-cursor` marker), the Claude-only Darwin brew check, and the `emit_context` shape.
321
323
 
324
+ **Shell deny tier on Claude Code and OpenCode — what is checked.** No live Claude Code or OpenCode session has run a refusal.
325
+
326
+ - Checked in this repo, by `.bkit/core/engine/audits/hooks/guardrails-parity.integration.test.ts` on the rendered hooks:
327
+ - The Claude hook, spawned with a `PreToolUse` payload for `env -u FOO git push -f origin dev`, prints `permissionDecision: "deny"` with a `permissionDecisionReason` and exits 0. It prints no deny for a quoted force-push sentence.
328
+ - The Codex hook prints `permissionDecision: "deny"` for the same commands.
329
+ - The Claude registration in `.bkit/shared/.claude/settings.json` ends in `|| true`, so the stdout JSON is the only way the hook refuses.
330
+ - The OpenCode plugin, imported in process, throws from its 1.x and 2.0 hooks for the force push, returns for `git status`, and returns for a payload that makes it error.
331
+ - Read from the installed OpenCode 2.1.4, not run in a session: `permission.bash` still applies, and a throw in `execute.before` fails the tool call before the command runs (§ Permissions / auto-approve).
332
+ - Read from vendor documentation only:
333
+ - Claude Code blocks a tool call on a `PreToolUse` hook's `permissionDecision: "deny"`, and on exit 2. Whether that deny outranks a `permissions.allow` rule such as `Bash(*)` in a live session is not checked.
334
+ - OpenCode 2.x has a top-level `permissions` list (`{ action: "shell", resource, effect }`).
335
+
322
336
  ### Rules-read advisory
323
337
 
324
338
  The session-start nudge, on all five hosts (Claude, Codex, Antigravity, Cursor, OpenCode). One constant sentence names `.agents/rules.md` as required reading and never names `AGENTS.md`. It never blocks a session and never changes an exit code. Delivery rides each host's earliest event: `SessionStart` where the host has one (Claude, Cursor), the first tool call where it does not (Codex, Antigravity, OpenCode).
@@ -352,17 +366,19 @@ What it advises:
352
366
  - Gate-config paths (JS / TS: tsconfig/eslint/prettier/vitest/jest/vale/slop/lint-staged; Python: ruff.toml/.ruff.toml/.flake8/mypy.ini/.mypy.ini/pylintrc/.pylintrc/pytest.ini; Go: golangci; Rust: clippy.toml/.clippy.toml/rustfmt.toml/.rustfmt.toml; mixed-purpose manifests such as package.json, pyproject.toml, setup.cfg, tox.ini are not matched) → "fix code, don't weaken gate" advisory, except under a consumer's `.bkit/templates/`, which holds reference copies. In bkit's own repo (package name `@cbartens/bkit`), that folder is the template source and stays guarded.
353
367
  - New-file writes → reuse-over-duplicate nudge.
354
368
  - `docs/**.md` (not `docs/plans/`) → density advisory appended.
369
+ - Agent-read files (below `.agents/`, `.bkit/` and `docs/`, plus `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`) → one general authoring reminder that points to `.bkit/authoring.md` § Which Sections Apply. It is the same on every edit method and does not pick sections by file kind.
370
+ - Shell edits by a known writer → the same per-file blocks and the same once-per-file record as the edit tools. The known writers are `>` / `>>` redirects, `sed -i` / `gsed -i`, `perl -i` / `ruby -i`, `awk` / `gawk -i inplace`, `tee`, `cp` / `mv`, `patch`, `git apply`, `git checkout -- <file>`, `prettier --write` / `-w` and `eslint --fix` (also behind `npx`, `pnpm exec`, `pnpm dlx`, `yarn` and `bunx`), `yq -i` and `dd of=`. bkit owns the list (`KNOWN_WRITERS` in `guardrails-shell.js`), and a consumer cannot extend it. A writer whose target is not on the command line (a variable, a directory, a patch body) gets one notice that some targets cannot be determined and the authoring reads apply to every file it writes. Every other command stays silent, script runners such as `node` and `python3` included.
355
371
 
356
372
  It is fail-open and includes subagents. It dedups on `(session, agent, file)` via OS-temp state, with a 24h TTL.
357
373
 
358
374
  <!-- prettier-ignore -->
359
375
  | Host | Implementation | File | Registration |
360
376
  | --- | --- | --- | --- |
361
- | Claude | `bkit-gateguard.cjs` (CJS) | `.claude/hooks/bkit-gateguard.cjs` | `.claude/settings.json` → `hooks.PreToolUse` on `Edit\|Write\|MultiEdit` |
377
+ | Claude | `bkit-gateguard.cjs` (CJS) | `.claude/hooks/bkit-gateguard.cjs` | `.claude/settings.json` → `hooks.PreToolUse` on `Edit\|Write\|MultiEdit\|NotebookEdit` (`notebook_path`) |
362
378
  | Codex | `bkit-gateguard.cjs` (CJS) — Claude's stdin / stdout contract; parses the `apply_patch` envelope for target paths | `.codex/hooks/bkit-gateguard.cjs` | `.codex/hooks.json` → `hooks.PreToolUse` on `apply_patch` |
363
- | Antigravity | `bkit-gateguard.cjs` (CJS) — Antigravity's `{ toolCall, conversationId }` stdin / `{ decision, reason }` stdout; `write_to_file` / `replace_file_content` edit tools, path from `args.TargetFile` | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` | `.agents/plugins/bkit/hooks.json` → `hooks.PreToolUse` on `write_to_file\|replace_file_content` |
364
- | Cursor | `bkit-gateguard.cjs` (CJS) — managed block generated from the same parts as the Claude twin, so byte-identical | `.cursor/hooks/bkit-gateguard.cjs` | `.cursor/hooks.json` → `preToolUse` (matcher `Write`), no `failClosed`, because an advisory hook that fails closed would block the edit it only meant to comment on |
365
- | Cursor | `bkit-guardrails.cjs` (CJS) — destructive-op / secret-exposure gates, the Cursor equivalent of Claude's `permissions` and OpenCode's `permission` map | `.cursor/hooks/bkit-guardrails.cjs` | `.cursor/hooks.json` → `beforeShellExecution` + `preToolUse` (`Read\|TabRead`), both `failClosed` |
379
+ | Antigravity | `bkit-gateguard.cjs` (CJS) — Antigravity's `{ toolCall, conversationId }` stdin / `{ decision, reason }` stdout; `write_to_file` / `replace_file_content` / `multi_replace_file_content` edit tools, path from `args.TargetFile` | `.agents/plugins/bkit/hooks/bkit-gateguard.cjs` | `.agents/plugins/bkit/hooks.json` → `hooks.PreToolUse` on `write_to_file\|replace_file_content\|multi_replace_file_content` |
380
+ | Cursor | `bkit-gateguard.cjs` (CJS) — managed block generated from the same parts as the Claude twin, so byte-identical | `.cursor/hooks/bkit-gateguard.cjs` | `.cursor/hooks.json` → `preToolUse` (matcher `Write\|Delete`), no `failClosed`, because an advisory hook that fails closed would block the edit it only meant to comment on |
381
+ | Cursor | `bkit-guardrails.cjs` (CJS) — destructive-op / secret-exposure gates, the Cursor equivalent of Claude's `permissions` and OpenCode's `permission` map. Claude's `bkit-guardrails.cjs` and OpenCode's `bkit-guardrails.js` refuse the same deny tier from the same parts, and leave the ask and secret tiers to those maps | `.cursor/hooks/bkit-guardrails.cjs` | `.cursor/hooks.json` → `beforeShellExecution` + `preToolUse` (`Read\|TabRead`), both `failClosed` |
366
382
  | OpenCode | `bkit-gateguard.js` (ESM) | `.opencode/plugin/bkit-gateguard.js` | `.opencode/opencode.json` → `plugin` array, spec `./plugin/bkit-gateguard.js` (config-file-relative; OpenCode 2.0 reads a bare `.opencode/…` spec as an npm package and fails to load — the plugin also auto-loads from `.opencode/plugin/`) |
367
383
 
368
384
  **Ownership:** both GateGuard files, and Cursor's `bkit-guardrails.cjs`, are markered-text (slash-comment: `// bkit:start` / `// bkit:end`). bkit owns only the advisory engine between the markers and reconverges it on every install / upgrade. The driver around it (Claude's stdin read and single `emit()`, OpenCode's exported `plugin`) is consumer-owned from first install onward, so consumer advisories survive upgrades. bkit's block is pure (no stdin, no stdout / stderr, no top-level call). Claude parses hook stdout as one JSON document, so two emitters would produce `{...}{...}`, and the whole hook's output, bkit's included, is discarded. On upgrade, a marker-less file is handled by its hash:
@@ -370,7 +386,7 @@ It is fail-open and includes subagents. It dedups on `(session, agent, file)` vi
370
386
  - **If** the hash matches a bkit release → the file is replaced wholesale.
371
387
  - **If** the hash is unknown → the block is appended, and wiring instructions are printed.
372
388
 
373
- Uninstall strips the block and leaves the consumer's driver working. `bkit-guardrails.cjs` follows the identical split: bkit owns `bkitGuardrails(payload)`, which returns a decision object or `null` for no-opinion, and the consumer owns the stdin read and the single `emit()`. The rules-read advisory hooks (`bkit-rules.cjs` on Codex and Antigravity, `bkit-rules.js` on OpenCode, § Rules-read advisory) follow the identical split.
389
+ Uninstall strips the block and leaves the consumer's driver working. `bkit-guardrails.cjs` follows the identical split: bkit owns `bkitGuardrails(payload)`, which returns a decision object or `null` for no-opinion, and the consumer owns the stdin read and the single `emit()`. OpenCode's `bkit-guardrails.js` splits the same way: bkit's block returns the refusal text or `null`, and the consumer-owned exported plugin throws it. The rules-read advisory hooks (`bkit-rules.cjs` on Codex and Antigravity, `bkit-rules.js` on OpenCode, § Rules-read advisory) follow the identical split.
374
390
 
375
391
  **Modes (env):**
376
392
 
@@ -400,6 +416,51 @@ The behaviour is the same, with four delivery mechanisms across five hosts. `.bk
400
416
 
401
417
  **Divergence budget:** every host's block carries `hooks/gateguard-engine.js` verbatim, and the Claude and Cursor blocks are byte-identical (both test-asserted on the generated hooks). OpenCode's block differs only where the runtime forces it: an ES module rather than CJS, the tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`, and a `patchText` envelope parser for `patch`. Codex's block differs only in its payload. Every edit arrives as `apply_patch` with a V4A envelope and no file path, so its block carries the envelope parser (Add / Update / Delete / Move-to targets). Antigravity's differs in its tool vocabulary (`write_to_file` / `replace_file_content`), its `TargetFile` extraction and the `antigravity-hook.js` contract part. Every advisory string, gate-config pattern and docs-path rule is identical across all five.
402
418
 
419
+ #### Shell edits, host coverage and delivery limits
420
+
421
+ Tool registration, target extraction and delivery are three separate checks. A fixture response proves emission only. Receipt by the model and a chance to read before the pending edit are separate claims, and no live run has established either on any host. Sources: [Claude context](https://code.claude.com/docs/en/hooks#add-context-for-claude) and [matchers](https://code.claude.com/docs/en/hooks#matcher-patterns), [Cursor hooks](https://cursor.com/docs/hooks), [Codex hooks](https://learn.chatgpt.com/docs/hooks), [Antigravity hook tools](https://antigravity.google/docs/hooks#supported-tools), [OpenCode V2 server plugins](https://dev.opencode.ai/v2/docs/build/plugins/server/). Capability last checked against those pages on 2026-11-02.
422
+
423
+ <!-- prettier-ignore -->
424
+ | Host | Edit tools covered | Shell covered | Delivery boundary |
425
+ | --- | --- | --- | --- |
426
+ | Claude | `Edit`, `Write`, `MultiEdit`, `NotebookEdit` | `Bash` | `PreToolUse.additionalContext` is emitted before the tool runs, but the model reads it on its next request beside the tool result. The reminder may reach the model only after the pending edit ran. |
427
+ | Cursor | `Write`, `Delete` | `beforeShellExecution` guard | The shipped edit driver sends `additional_context` on an allow. Current docs describe `agent_message` for a denied call, so the `additional_context` envelope is unverified. Shell hooks document `agent_message` separately. |
428
+ | Codex | `apply_patch` (every target in the batch) | `Bash` initial commands | `PreToolUse.additionalContext` is documented as model-visible. Timing before the pending edit is unverified. Later interactive input through `write_stdin` is not checked. The `.codex/` layer must be trusted. |
429
+ | Antigravity | `write_to_file`, `replace_file_content`, `multi_replace_file_content` | `run_command` | Deny once with the reminder as `reason`, then allow the identical retry. No new shell denial. |
430
+ | OpenCode | `write`, `edit`, `patch` | none | The advisory is appended to the tool result after the edit. This is an explicit gap: it is not before-edit coverage, and the shell plugin `bkit-guardrails.js` refuses the deny tier only and gives no edit advice. |
431
+
432
+ Arbitrary custom or MCP tools are not inferred from a generic tool name.
433
+
434
+ **Default Cursor driver.** In `.cursor/hooks/bkit-gateguard.cjs` the consumer-owned outer driver reads the payload and emits the `additional_context` envelope. A managed-block update cannot change that envelope or add fields the driver drops, so edit delivery on a default install is unverified, and upgrades leave the driver bytes as they are. Check the installed Cursor version's pre-tool response contract first and keep custom driver text. If that version has no verified non-blocking before-edit route, keep the coverage limit. Do not rename a field by guesswork or use denied or post-tool delivery instead.
435
+
436
+ **Customized drivers.** A customized outer driver stays consumer-owned. When the managed block cannot carry the new behavior through it, the install is not equivalent to the default. Name the exact wiring boundary in your own docs.
437
+
438
+ **Response budgets.** The engine adds only complete per-file blocks, and counts the whole added context: the shell introduction, the blocks and the notices. It reserves 512 characters (Claude, OpenCode) or bytes (the others) of the budget for notices. Composed shell advice counts its own text, so the omitted-target notice is sized exactly instead.
439
+
440
+ <!-- prettier-ignore -->
441
+ | Host | Budget | Basis |
442
+ | --- | --- | --- |
443
+ | Claude | 8,000 characters | Below the documented 10,000-character spill threshold. |
444
+ | Codex | 2,000 UTF-8 bytes | Below the documented default of about 2,500 tokens. |
445
+ | Cursor, Antigravity | 2,000 bytes | Provisional until the route is verified. |
446
+ | OpenCode | 8,000 characters | Same limit as Claude (`ADVICE_BUDGETS.opencode`). |
447
+
448
+ These are conservative limits, not measured visibility guarantees. A target whose block does not fit is left unacknowledged, so a later exact edit warns again. The shell path inspects at most 256 KiB of command text, nesting depth 3 and 64 exact targets, with a cooperative 200 ms deadline. Each rendered shell hook must finish within the smaller of one second and a quarter of its host's documented timeout.
449
+
450
+ **Diagnostic signatures.** These are the six recovery cases, named here so an agent can match what it sees. The hooks emit no signature string: the advisory carries plain prose for `analysis-unavailable` ("Some targets cannot be determined"), `analysis-limit` ("Analysis limit reached") and `output-limit` ("omitted (output limit)"). The other three have no advisory text; the recovery column is the only guidance. None is a counter, a service or a command log, and none includes raw commands, inline source or environment values.
451
+
452
+ <!-- prettier-ignore -->
453
+ | Signature | Meaning | Recovery |
454
+ | --- | --- | --- |
455
+ | `analysis-unavailable` | A known writer's target is not a literal path (a variable, a directory, a patch body), or the working directory is unresolved. | Targets are unknown and unacknowledged. Check the files the command writes and the directory yourself. |
456
+ | `analysis-limit` | A byte, nesting, target or time bound stopped inspection. | Targets found so far are kept. The authoring reads still apply to every file edited. |
457
+ | `output-limit` | The host budget left out complete blocks for known targets. | The notice carries the omitted count. Omitted paths stay unacknowledged. Do not treat the batch as full coverage. |
458
+ | `state-fallback` | The warning state is corrupt or unwritable. | The hook uses its in-process fallback, allows the call and may repeat advice. Check the state directory and its permissions, then reset the session state. Do not infer delivery from a partial file. |
459
+ | `delivery-unverified` | The host route, project trust or timing is not established. | Check event registration, the tool payload, project trust and the table above. A fixture response is not proof of live delivery. |
460
+ | `driver-wiring` | A preserved driver has input or response wiring the managed block cannot work with, including the default Cursor envelope. | Compare that driver with the host's current documented contract and keep custom text. State the limit when no supported route exists. |
461
+
462
+ `BKIT_GATEGUARD=off` silences the advice and leaves the independent shell protections in place.
463
+
403
464
  ### ReadGuard
404
465
 
405
466
  An advisory repeat-read hook, on all five hosts. When the same agent reads a line range it already read in this conversation, and the file is unchanged since (same mtime and size), the read gets a note: use the earlier output, and re-read only if it left context (summarised, or read by another agent).
@@ -436,16 +497,16 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
436
497
  | Concern | Claude | Codex | Antigravity | Cursor | OpenCode |
437
498
  | --- | --- | --- | --- | --- | --- |
438
499
  | File / secrets — read tool | `.claude/settings.json` → `permissions` `Read(...)`: `*.pem` / `*.p12` / `id_rsa` deny; `.env` / `.env.*` ask — `.env.example` too: its `allow` row never fires, `ask` is evaluated before `allow` | none — no file-read tool | `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` via `PreToolUse` (`view_file`, path `AbsolutePath`) — key deny; `.env` / `.env.*` ask (Antigravity's own `ask`); `.env.example` allowed | `.cursor/hooks/bkit-guardrails.cjs` via `preToolUse` (`Read\|TabRead`) — key deny; `.env` / `.env.*` ask; `.env.example` allowed | `.opencode/opencode.json` → `permission.read` map — key deny; `.env` / `.env.*` ask; `.env.example` allowed |
439
- | File / secrets — shell (`cat .bkit/.env`) | not gated — no `Bash(...)` rows: a command-text glob cannot tell `cat .env` from `cp .env.example .env`, a grep pattern or a commit message, and an ask stalls autonomous and cloud runs. A file command Claude recognises (`cat`, `head`, `tail`, `sed`, `tee`) on a key file still hits the `Read(...)` deny, which Claude applies to those commands | same detection as Cursor via `PreToolUse` (`Bash`) — advisory `additionalContext`, command runs | same detection as Cursor via `PreToolUse` (`run_command`) — Antigravity's own `ask` | `beforeShellExecution` ask on any program reading `.env`, `.env.*` (not `.env.example`), `*.pem`, `*.p12` or `id_rsa` (args, `< file`, `--opt=file`, `@file`, `rev:file`, copy sources, `sh -c` scripts); redirect targets, copy destinations, grep / rg patterns, comments and `ls` / `stat` / `test` / `touch` / `rm` / `mv` / `ln` / `chmod` / `echo` pass | not gated — no `permission.bash` rows, same reason as Claude |
440
- | Shell / destructive | `permissions.deny` globs on force-push in any argument position — `--force`, `-f` / `-f…` cluster, `+refspec`, never `--force-with-lease` — plus `rm -rf` / `rm -fr` on `/*`, `~`, `~/*`, `$HOME`, `$HOME/*`, `${HOME}`, `${HOME}/*`, `chmod -R 777 /`; `permissions.ask` globs on publish, destructive gh, and destructive git in common flag orders (`git reset … --hard`, forced `git clean` (`-…f…`), whole-tree `git checkout` / `git restore`, `git rebase … -i`, `git stash drop` / `git stash clear`, `git filter-branch`), `--no-verify` on any git subcommand, `git commit -n`. Force-push and `reset --hard` globs also cover git global options before the subcommand (`git -C dir push --force`, `git -c k=v push origin +ref`, `git -C dir reset --hard`) and `f` second in a cluster (`-uf`, `-vf`). Globs match the command text, so `f` later in a cluster (`-uvf`) is not matched; the parsed hosts catch it. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` tool is allowlisted | `.codex/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) — Cursor's parsed tiers; deny blocks; ask emitted as advisory `additionalContext`, command runs (Codex cannot prompt) | same hook via `PreToolUse` (`run_command`) — Cursor's parsed tiers; deny blocks every time; ask = Antigravity's own `ask` | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same tiers, classified on the parsed command: git subcommand after global options (`-C`, `-c`, `--git-dir`, …), flags in any order, short clusters expanded, option values never read as flags; every `&&` / `;` / `\|` segment, `sh -c` script and `$(…)` substitution. `git clean -n` / `--dry-run` and `git restore --staged .` pass | `permission.bash` deny / ask globs, last match wins — same globs and gap as Claude |
441
- | Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install / upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` off `.bkit/allowlist.json` → advisory `additionalContext`, command runs | `curl`/`wget` off `.bkit/allowlist.json` → denied once with the advisory, retry passes; `read_url` / `search_web` ungated | `curl`/`wget` ask unless host in `.bkit/allowlist.json` (tooling and consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool and `curl *`/`wget *` ask → `curl *{domain}*`/`wget *{domain}*` allow for shell, from the same allowlist (baked into `opencode.json`) |
442
- | Granularity | Per-tool glob | Hook script (project-scoped, fail-open; fires only once `.codex/` is trusted) | Hook script (workspace plugin, fail-open) | Hook script (project-scoped, fail-open; `failClosed` blocks only a crashed hook) | Per-path / per-command glob in `permission` |
500
+ | File / secrets — shell (`cat .bkit/.env`) | not gated — no `Bash(...)` rows: a command-text glob cannot tell `cat .env` from `cp .env.example .env`, a grep pattern or a commit message, and an ask stalls autonomous and cloud runs. A file command Claude recognises (`cat`, `head`, `tail`, `sed`, `tee`) on a key file inside the project still hits the `Read(...)` deny, which Claude applies to those commands | same detection as Cursor via `PreToolUse` (`Bash`), plus a deny for a command that exposes a private key's content (configured to deny, not verified on a real Codex host). Key files: `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` (not `*.pub`), `*.pem`, `*.p12`, `*.pfx`, `*.key`, and a glob that can match one of those names (`~/.ssh/*`, `~/.ssh/id_*`, `*.pem`; not `~/.ssh/*.pub` or a bare `*`). Exposing is printing: a file operand of a program that prints it (`cat`, `head`, `base64`, the file after a `grep` / `sed` / `awk` pattern unless an option supplies the pattern, skipping option values such as `grep -A 2`), a `<` input file, `dd if=`, `git show` / `git cat-file` of `rev:path`, `git diff --no-index`, the `-in` file of `openssl base64` / `enc` / `asn1parse`, or the input of `openssl rsa` / `pkey` / `ec` / `dsa` / `pkcs8` / `pkcs12` / `storeutl` unless `-pubout`, `-noout` or `pkcs12 -nokeys` leaves the key out and no `-text` puts it back. Exposing is also sending: an `@file` word (`curl -d @key.pem`, `-F f=@key.pem`), `curl -T` / `wget --post-file`, or an `scp` / `rsync` source copied to `host:`. All of it is found through wrappers and `sh -c` scripts. A key a program only uses (`ssh -i`, `curl --cacert`, `openssl x509 -in`), writes (`-out`, `-keyout`, `ssh-keygen -f`), edits in place (`sed -i`) or names (`git rm`, `git add`, `git commit -m`, `ls`) gets the advisory. The rule goes by file name: a key copied or linked to another name, a path in a variable, `xargs`, `find -exec`, `source` and script languages are not caught. Every other secret read, `.env` / `.env.*` included, is advisory `additionalContext` and the command runs | same detection as Cursor via `PreToolUse` (`run_command`) — Antigravity's own `ask` | `beforeShellExecution` ask on any program naming `.env`, `.env.*` (not `.env.example`) or a key file of the Codex column, globs included (args, option values, `< file`, `--opt=file`, `@file`, `rev:file`, copy sources, `sh -c` scripts); redirect targets, copy destinations, grep / rg patterns (past option values such as `grep -A 2`), `jq` / `yq` filters, comments and `ls` / `stat` / `test` / `touch` / `rm` / `mv` / `ln` / `chmod` / `echo` pass | not gated — no `permission.bash` rows, same reason as Claude |
501
+ | Shell / destructive | `permissions.deny` globs on force-push in any argument position — `--force`, `-f` / `-f…` cluster, `+refspec`, never `--force-with-lease` — plus `rm -rf` / `rm -fr` on `/*`, `~`, `~/*`, `$HOME`, `$HOME/*`, `${HOME}`, `${HOME}/*`, `chmod -R 777 /`; `permissions.ask` globs on publish, destructive gh, and destructive git in common flag orders (`git reset … --hard`, forced `git clean` (`-…f…`), whole-tree `git checkout` / `git restore`, `git rebase … -i`, `git stash drop` / `git stash clear`, `git filter-branch`), `--no-verify` on any git subcommand, `git commit -n`. Force-push and `reset --hard` globs also cover git global options before the subcommand (`git -C dir push --force`, `git -c k=v push origin +ref`, `git -C dir reset --hard`) and `f` second in a cluster (`-uf`, `-vf`). Globs match the command text, so `f` later in a cluster (`-uvf`) or a program behind `env -u FOO` is not matched; `.claude/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) refuses the deny tier on the parsed command (`permissionDecision: "deny"`), so it catches both. Shell `curl` / `wget` are not gated here — `permissions` cannot match a URL host, so only the `WebFetch` tool is allowlisted | `.codex/hooks/bkit-guardrails.cjs` via `PreToolUse` (`Bash`) — Cursor's parsed tiers; deny blocks; ask emitted as advisory `additionalContext`, command runs (Codex cannot prompt) | same hook via `PreToolUse` (`run_command`) — Cursor's parsed tiers; deny blocks every time; ask = Antigravity's own `ask` | `.cursor/hooks/bkit-guardrails.cjs` via `beforeShellExecution` — same tiers, classified on the parsed command: git subcommand after global options (`-C`, `-c`, `--git-dir`, …), flags in any order, short clusters expanded, option values never read as flags; every simple command the quote-aware parser finds (`guardrails-shell.js` row above): each `&&` / `;` / `\|` list member, `sh -c` / `bash -c` script, `eval`, `env -S`, `find -exec`, `$(…)` and backtick substitution, `( … )` subshell, a heredoc or here-string fed to a shell and literal `echo` / `printf` / `cat <<` text piped into a shell, with wrappers (`env`, `timeout`, `nice`, `sudo`, `doas`, …) skipped. Words only inside quotes, or in a heredoc body fed to a non-shell, are data and never refused. `git clean -n` / `--dry-run` and `git restore --staged .` pass | `permission.bash` deny / ask globs, last match wins — same globs and gap as Claude. OpenCode 2.1.4 applies them: it turns each `permission.bash` row into a `shell` rule of its `permissions` list (seen in `opencode debug config` output on 2.1.4). `.opencode/plugin/bkit-guardrails.js` refuses the deny tier on the parsed command by throwing in `execute.before` (`tool.execute.before` on 1.x); on 2.1.4 that throw fails the tool call before the command runs (read in the 2.1.4 binary's bundled source; the vendor plugin page does not say). The throw itself is checked in process by `.bkit/core/engine/audits/hooks/guardrails-parity.integration.test.ts`; no test runs a live OpenCode session |
502
+ | Network fetch | `WebSearch` + tooling `WebFetch(domain:…)`; install / upgrade enriches from the shipped egress registry union consumer `allowed-domains` in `.agents/context.md` (stack hosts never shipped), recording what it wrote so it can later prune it | `curl`/`wget` off `.bkit/allowlist.json` → advisory `additionalContext`, command runs | `curl`/`wget` off `.bkit/allowlist.json` → denied once with the advisory, retry passes; `read_url` / `search_web` ungated | `curl`/`wget` ask unless host in `.bkit/allowlist.json` (tooling and consumer domains) | `websearch` allow; `webfetch` URL map (`"*": ask` → `*{domain}*: allow`) for the fetch tool, from the same allowlist (baked into `opencode.json`); shell `curl *`/`wget *` ask with no derived allow |
503
+ | Granularity | Per-tool glob, plus a fail-open hook script for the shell deny tier | Hook script (project-scoped, fail-open; fires only once `.codex/` is trusted) | Hook script (workspace plugin, fail-open) | Hook script (project-scoped, fail-open; `failClosed` blocks only a crashed hook) | Per-path / per-command glob in `permission`, plus a fail-open plugin for the shell deny tier |
443
504
  | Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | host defaults — bkit writes no `.codex/config.toml` | host defaults — bkit ships none | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults |
444
505
  | MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | none written | none written | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
445
506
  | MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | none — no project-level MCP approval file | none written | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
446
507
  | Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | `~/.codex/config.toml` | user-level settings | Cursor project / user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` |
447
508
 
448
- **Install behaviour:** template drops, each a host-specific encoding of the same shared policy. There is no single canonical JSON. Each host's native form is kept in lockstep, and `.bkit/core/engine/install/modules/index.integration.test.ts` § permissions-parity asserts it. Machine-local paths stay out of templates.
509
+ **Install behaviour:** template drops, each a host-specific encoding of the same shared policy. No single canonical JSON exists. Each host's native form is kept in lockstep, and `.bkit/core/engine/install/modules/index.integration.test.ts` § permissions-parity asserts it. Machine-local paths stay out of templates.
449
510
 
450
511
  ### Network allowlist — one source, five hosts
451
512
 
@@ -456,11 +517,11 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
456
517
  <!-- prettier-ignore -->
457
518
  | Host | Where the allowlist lives | Why that shape |
458
519
  | --- | --- | --- |
459
- | **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked against `.bkit/allowlist.json` by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model for the fetch tool. Shell `curl` is not domain-gated at all — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)` with `deny` + the auto-mode classifier as backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
460
- | **Codex** | Reads the same `.bkit/allowlist.json` at runtime via `.codex/hooks/bkit-guardrails.cjs` | Codex has no project-level permission file. The hook host-parses `curl`/`wget` and emits an advisory `ask` — Codex cannot prompt, so the allowlist informs rather than enforces. |
461
- | **Antigravity** | Reads the same `.bkit/allowlist.json` at runtime via `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` | Antigravity has no project-level permission file. The hook host-parses `curl`/`wget` on the `run_command` matcher and denies a non-allowlisted fetch once with the advisory as the reason; the retry passes. |
520
+ | **Claude** | `.claude/settings.json` `WebFetch(domain:…)` allow rules; shell fetches host-checked against `.bkit/allowlist.json` by `.claude/hooks/bkit-guardrails.cjs` (advisory) | Claude has a first-class settings permission model for the fetch tool. Shell `curl` is not domain-enforced — Claude rules match a command prefix, not a URL host, so `curl` runs under `Bash(*)`, the hook only advises, and `deny` + the auto-mode classifier are the backstops. Prefer `WebFetch` for allowlisted hosts; context-fetch uses `curl` / CLI under `Bash(*)`. |
521
+ | **Codex** | Reads the same `.bkit/allowlist.json` at runtime via `.codex/hooks/bkit-guardrails.cjs` | Codex has no project-level permission file. The hook flags a `curl` / `wget` that the parser reads as a program, not one named only inside quotes, and emits an advisory unless every URL host in the command is on the allowlist — Codex cannot prompt, so the allowlist informs rather than enforces. |
522
+ | **Antigravity** | Reads the same `.bkit/allowlist.json` at runtime via `.agents/plugins/bkit/hooks/bkit-guardrails.cjs` | Antigravity has no project-level permission file. The hook flags a `curl` / `wget` that the parser reads as a program on the `run_command` matcher, the same way as Codex, and denies a non-allowlisted fetch once with the advisory as the reason; the retry passes. |
462
523
  | **Cursor** | Generated `.bkit/allowlist.json` read at runtime by `.cursor/hooks/bkit-guardrails.cjs` | Cursor has no project settings equivalent to Claude `permissions` / OpenCode `permission` for curl host globs. Parity is a hook (`beforeShellExecution`): ask on `curl`/`wget` unless every URL host is on the allowlist. |
463
- | **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool, and `permission.bash` `curl *`/`wget *` ask then `curl *{domain}*`/`wget *{domain}*` allow for shell fetch (last-match-wins on both) | Both fetch surfaces are domain-gated, so an allowlisted host does not prompt whichever path the agent takes. `webfetch` matches the resource against the requested URL, `bash` against the command string. **Looser than Claude's `domain:`:** OpenCode globs match the whole string (`*` → `.*`, crossing `/` `?` `@`), so `*{domain}*` allows the domain anywhere in the URL or command — apex and every subdomain, but also `https://evil.tld/?x={domain}`. Accepted risk: no OpenCode glob covers subdomains without it. No separate allowlist file. |
524
+ | **OpenCode** | Baked into `.opencode/opencode.json`: `permission.webfetch` URL map (`"*": "ask"` then `*{domain}*: allow`) for the fetch tool (last-match-wins). Shell `curl *`/`wget *` keep their ask: no allow is derived for them, because a glob over the command string also matches a host in a query or user-info part. Substring `curl` / `wget` allows an earlier install wrote are reported by the `opencode-substring-fetch-grants` advisory for owner review, never removed | Only the fetch tool is domain-allowed, so an allowlisted host does not prompt there; shell fetches ask. `webfetch` matches the resource against the requested URL. **Looser than Claude's `domain:`:** OpenCode globs match the whole string (`*` → `.*`, crossing `/` `?` `@`), so `*{domain}*` allows the domain anywhere in the URL — apex and every subdomain, but also `https://evil.tld/?x={domain}`. Accepted risk (decision 551): no OpenCode glob covers subdomains without it. No separate allowlist file. |
464
525
 
465
526
  **`.bkit/allowlist.json`:** core-owned. It is written on every install / upgrade whatever the host set, and removed by full uninstall. Do not hand-edit it, because install / upgrade rewrites it whole. Change `allowed-domains` instead. `bkit check` fails when it is missing or stale. The hook finds it from the payload's repo dirs (`workspace_roots`, `cwd`, Antigravity `workspacePaths`), then its own cwd, walking up to the `.git` root, because Antigravity runs plugin hooks from the plugin dir. When the file is missing, every host reads as unknown. The hook embeds no list, because a second copy drifts from the registry silently.
466
527
 
@@ -473,7 +534,7 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
473
534
  <!-- prettier-ignore -->
474
535
  | Host | Where the allows live | Rule per server `<s>` |
475
536
  | --- | --- | --- |
476
- | **Claude** | `.claude/settings.json` `permissions.allow`, recorded in `.bkit/version` `claudeAllowDerived` so a server dropped from the block is pruned | `mcp__<s>__*` (`.mcp.json` servers; claude.ai connectors in cloud sessions) + `mcp__claude_ai_<s>__*` (claude.ai connectors in the local CLI) |
537
+ | **Claude** | `.claude/settings.json` `permissions.allow`, recorded in `.bkit/version` `claudeAllowDerived` so a server dropped from the block is pruned; `bkit uninstall` removes only the rows that record holds and lists other derived-looking rows for owner review | `mcp__<s>__*` (`.mcp.json` servers; claude.ai connectors in cloud sessions) + `mcp__claude_ai_<s>__*` (claude.ai connectors in the local CLI) |
477
538
  | **Cursor** | Generated `.cursor/cli.json` `permissions.allow` — Cursor CLI + cloud agents. The IDE agent's MCP auto-run list is user-level only | `Mcp(<s>:*)` |
478
539
  | **OpenCode** | Baked into `.opencode/opencode.json` → `permission` | `"<s>_*": "allow"` — OpenCode names MCP tools `<s>_<tool>` |
479
540
 
@@ -575,7 +636,7 @@ bkit ships no default: the setting also hides each person's own connectors (mail
575
636
  | Default network | `Trusted` allowlist (npm, GitHub, PyPI, Docker Hub, vale tarball) | **Internet access**: package-manager domains + **Additional allowed domains** (`*.` entries untested), or all public internet | Outbound open in the sandbox |
576
637
  | Reusable across repos | Setup script yes (generic snapshot); environment no — one per repo (secrets / PAT scope are per-repo) | Install script yes; environment one per repo; **Personal vault** shares chosen secrets | No — Dockerfile per repo (copied from the bkit template and owned by the repo) |
577
638
  | Secrets | Env vars in Claude app (plaintext; rotate PATs) | **Environment variables**; **Network secrets** = proxy-substituted, HTTP-only | Cursor Cloud env vars (Settings → Background Agents → Environment Variables) |
578
- | Linear preflight + rules advisory | `.claude/hooks/bkit-preflight.sh` (SessionStart, non-blocking — one document carrying the rules-read advisory always, plus the guard's `additionalContext` HARD STOP when a tracker issue id is set) | `.codex/hooks/bkit-rules.cjs` advisory — unproven in cloud tasks | `.cursor/hooks/bkit-preflight.sh` (`sessionStart`, `failClosed: true`, blocks on non-zero; the same advisory + guard document) |
639
+ | Tracker preflight + rules advisory | `.claude/hooks/bkit-preflight.sh` (SessionStart, non-blocking — one document carrying the rules-read advisory always, plus the guard's `additionalContext` HARD STOP when a tracker issue id is set) | `.codex/hooks/bkit-rules.cjs` advisory — unproven in cloud tasks; no tracker guard (Codex Cloud is unguarded). Router: `bkit install --auto=codex --codex` adds the `codex` job in `bkit-cloud.yml` (`openai/codex-action`, `BKIT_OPENAI_API_KEY`) | `.cursor/hooks/bkit-preflight.sh` (`sessionStart`, `failClosed: true`, blocks on non-zero; the same advisory + guard document) |
579
640
 
580
641
  **Install behaviour:** template drops, with project tokens filled at install. bkit aligns all clouds on vale 3.9.1, pnpm (corepack-pinned `package.json#packageManager`) and the gh CLI. See `.bkit/cloud.md` for the paste-in recipe and the sharing pattern.
581
642
 
@@ -777,7 +838,7 @@ Cells show pin · score · $/task. Deltas are against that column's target. Key
777
838
 
778
839
  **Hard-constraint escape hatch.** "Cheapest that reaches the target" is bounded by constraints that are not about quality: paid-plan gating (`ollama`), and rate/quota/context walls when 39 agents collapse onto one flagship. Deviate for those, and say so in the Notes cell. A constrained pin must never read as a tier judgement.
779
840
 
780
- The cloud OpenAI-compatible cells are tool-call-smoked (a `tools:` round-trip returns `tool_calls`), because a listing in `/models` does not prove the model can call tools. `opencode-zen` is existence-validated via models.dev (the Zen balance is zero, so the smoke runs on the Go endpoint). To re-pin, edit the agent's `model:`, add a `prompts.md` § Model Overrides row, or change the column and run `bkit check`. Probe the live catalog first (models.dev for OpenCode; the `/v1/models` table for the rest).
841
+ The current cloud OpenAI-compatible pins are existence-validated only (`prompts.md` § Live model-ID verification). A tool-call smoke (a `tools:` round-trip returns `tool_calls`) is the stronger check, because a listing in `/models` does not prove the model can call tools. `opencode-zen` is existence-validated via models.dev. To re-pin, edit the agent's `model:`, add a `prompts.md` § Model Overrides row, or change the column and run `bkit check`. Probe the live catalog first (models.dev for OpenCode; the `/v1/models` table for the rest).
781
842
 
782
843
  **Consumer model overrides (upgrade-safe):** `.bkit/prompts.md` is marker-managed (the `rules.md` pattern). bkit refreshes `bkit:start`/`bkit:end` on upgrade, and `## Model Overrides` below `bkit:end` is consumer-owned. Pin a different model per agent and host/provider:
783
844
 
@@ -821,7 +882,7 @@ The cloud OpenAI-compatible cells are tool-call-smoked (a `tools:` round-trip re
821
882
  | Claude | First-class `Skill` tool. Registered via `.claude/settings.json` → `permissions.allow: ["Skill(*)"]`. Discoverable via plugin marketplace. | `~/.claude/skills/` (user) + `.agents/skills/` (project) + plugin skill dirs |
822
883
  | Cursor | Cursor 2.4+ Agent Skills (similar shape). | `.cursor/skills/` (per docs); `.agents/skills/` referenced via custom routing |
823
884
 
824
- `.agents/skills/` = **canonical project skill directory**. Both hosts read it. There is no per-host transform. Skills are listed in `.agents/skills.md`.
885
+ `.agents/skills/` = **canonical project skill directory**. Both hosts read it. No per-host transform exists. Skills are listed in `.agents/skills.md`.
825
886
 
826
887
  ---
827
888
 
@@ -855,7 +916,7 @@ A full test gate runs for minutes, and a gate that waits for the machine-wide te
855
916
  | Cursor | No documented limit for the agent terminal; the CLI's Shell Mode stops a command after 30 seconds | Not documented | Not documented | unset → 60 s, then exit 81 and a re-run |
856
917
  | OpenCode | `bash` runs in the foreground until the call's timeout | Stopped; no background option | No | unset → 60 s, then exit 81 and a re-run |
857
918
 
858
- **Rule:** a bkit verb that may wait on another process bounds the wait by `BKIT_LOCK_WAIT_S` (default 60 s), prints who it is waiting for and how long that holder's last run took, and exits 81 naming the holder when the wait runs out; every workflow block that runs such a verb routes 81 → end turn, re-run the block. A host that keeps a command alive past its call and reports its exit gets a long budget, so one call outlasts the holder. Every other host loops in short calls, which costs a re-run per minute of waiting and nothing else.
919
+ **Rule:** a bkit verb that may wait on another process bounds the wait by `BKIT_LOCK_WAIT_S` (default 60 s), prints who it is waiting for and how long that holder's last run took, and exits 81 naming the holder when the wait runs out; every workflow block that runs such a verb routes 81 → end turn, re-run the block. A host that keeps a command alive past its call and reports its exit gets a long budget, so one call outlasts the holder. Every other host loops in short calls, which costs a re-run per minute of waiting and nothing else: a re-run within 120 seconds keeps its place in line.
859
920
 
860
921
  **Sources:** Claude tools reference (<https://code.claude.com/docs/en/tools-reference>, § Bash tool: timeout and output limits, background commands, time limit for background commands, foreground commands that move to the background); Codex config reference (<https://learn.chatgpt.com/docs/config-file/config-reference>, `features.unified_exec`, `background_terminal_max_timeout`); Antigravity hooks reference (<https://antigravity.google/docs/hooks/>, `run_command`, `manage_task`, Stop `fullyIdle`); Cursor CLI Shell Mode docs. The Cursor agent tools and terminal pages and the OpenCode tools page state no timeout and no background contract.
861
922