@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
@@ -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,10 +76,12 @@ 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
 
83
+ OpenCode installation detection uses `.opencode/agents/`. Residual runtime files in `.opencode/` after uninstall do not mark the integration as installed or require a provider.
84
+
83
85
  A new host needs a row in the table above, a `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`), a manifest block (`.bkit/core/engine/install/manifest.ts`), `.bkit/core/.<host>/hooks/` (with the host config JSON in `.bkit/shared/.<host>/`), a GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts` and a ReadGuard case in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`. A new provider needs an entry in `OPENCODE_PROVIDERS` (`.bkit/core/engine/shared/egress.ts`), after which `tsc` demands its `OPENCODE_PROVIDER_DEFAULTS` and `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) entries. It also needs a curated `prompts.md` § Models column.
84
86
 
85
87
  ---
@@ -146,7 +148,7 @@ The persistent variant is a `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgen
146
148
  | --- | --- | --- | --- | --- |
147
149
  | `name` | required | required | required | kebab-case, must match filename. Identical. |
148
150
  | `description` | required | required | required | Identical. |
149
- | `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. |
150
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_*`). |
151
153
  | `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and OpenCode. |
152
154
  | `maxTurns` | required | not supported | not supported | Drop on Cursor and OpenCode. |
@@ -172,16 +174,16 @@ Cursor model assignment: § Models below. It is a per-agent lookup, not derived
172
174
 
173
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.
174
176
 
175
- > **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.
176
178
 
177
179
  Tier guidance:
178
180
 
179
181
  - **`composer-2.5`** ($) — default. Fast and cheap: build executors, utilities, and the `/build` and `/ship` orchestrators. First-party pool.
180
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.
181
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.
182
- - **`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.
183
185
  - **`gpt-5.*`** ($$$) — override only. An API-pool diversity hedge (`gpt-5.6-sol-high`, …). Not pinned.
184
- - **`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.
185
187
 
186
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`.
187
189
 
@@ -265,10 +267,10 @@ Per-action gates on all five hosts, subagents included. This section is an overv
265
267
  <!-- prettier-ignore -->
266
268
  | Guard | Trigger | Effect | Enforcement |
267
269
  | --- | --- | --- | --- |
268
- | 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 |
269
- | 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 |
270
272
  | Network | `curl` / `wget`, fetch tool | ask unless host in allowlist (§ Network allowlist) | Advisory on Claude shell, Codex; Antigravity denies once, retry passes |
271
- | 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 |
272
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 |
273
275
  | ReadGuard | Repeat read of an unchanged range | Use-earlier-output note | Advisory, never blocks |
274
276
 
@@ -296,27 +298,41 @@ Per-action gates on all five hosts, subagents included. This section is an overv
296
298
  <!-- prettier-ignore -->
297
299
  | Part | Shared by | Holds |
298
300
  | --- | --- | --- |
299
- | `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 |
300
302
  | `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
301
303
  | `readguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
302
304
  | `readguard-payload.js` | Claude, Codex, Antigravity, Cursor `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
303
305
  | `antigravity-hook.js` | Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
304
- | `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) |
305
- | `guardrails-tiers.js` | Codex, Antigravity, Cursor `guardrails` | git parsing (`parseGit`), deny + ask rules, `secretFileKind`, shell secret-read detection, `classifyShell` precedence |
306
- | `guardrails-read.js` | Antigravity, Cursor `guardrails` | `classifyRead` over `secretFileKind`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
307
- | `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 |
308
311
  | `preflight-rules.sh` | Claude, Cursor `preflight` | the rules-read advisory sentence and its `emit_context` call, merged into the one SessionStart JSON document |
309
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) |
310
313
 
311
314
  Per host, outside the parts:
312
315
 
313
- - 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.
314
317
  - Codex: the `apply_patch` envelope parser, with the ask tier emitted as advisory.
315
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`).
316
319
  - Cursor: the `{ permission }` output, guardrails `Read|TabRead` path extraction, and gateguard workspace-relative path resolution.
317
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.
318
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.
319
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
+
320
336
  ### Rules-read advisory
321
337
 
322
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).
@@ -350,17 +366,19 @@ What it advises:
350
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.
351
367
  - New-file writes → reuse-over-duplicate nudge.
352
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.
353
371
 
354
372
  It is fail-open and includes subagents. It dedups on `(session, agent, file)` via OS-temp state, with a 24h TTL.
355
373
 
356
374
  <!-- prettier-ignore -->
357
375
  | Host | Implementation | File | Registration |
358
376
  | --- | --- | --- | --- |
359
- | 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`) |
360
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` |
361
- | 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` |
362
- | 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 |
363
- | 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` |
364
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/`) |
365
383
 
366
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:
@@ -368,7 +386,7 @@ It is fail-open and includes subagents. It dedups on `(session, agent, file)` vi
368
386
  - **If** the hash matches a bkit release → the file is replaced wholesale.
369
387
  - **If** the hash is unknown → the block is appended, and wiring instructions are printed.
370
388
 
371
- 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.
372
390
 
373
391
  **Modes (env):**
374
392
 
@@ -398,6 +416,51 @@ The behaviour is the same, with four delivery mechanisms across five hosts. `.bk
398
416
 
399
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.
400
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
+
401
464
  ### ReadGuard
402
465
 
403
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).
@@ -434,16 +497,16 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
434
497
  | Concern | Claude | Codex | Antigravity | Cursor | OpenCode |
435
498
  | --- | --- | --- | --- | --- | --- |
436
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 |
437
- | 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 |
438
- | 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 |
439
- | 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`) |
440
- | 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 |
441
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 |
442
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` |
443
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"` |
444
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` |
445
508
 
446
- **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.
447
510
 
448
511
  ### Network allowlist — one source, five hosts
449
512
 
@@ -454,11 +517,11 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
454
517
  <!-- prettier-ignore -->
455
518
  | Host | Where the allowlist lives | Why that shape |
456
519
  | --- | --- | --- |
457
- | **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(*)`. |
458
- | **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. |
459
- | **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. |
460
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. |
461
- | **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. |
462
525
 
463
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.
464
527
 
@@ -471,7 +534,7 @@ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readg
471
534
  <!-- prettier-ignore -->
472
535
  | Host | Where the allows live | Rule per server `<s>` |
473
536
  | --- | --- | --- |
474
- | **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) |
475
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>:*)` |
476
539
  | **OpenCode** | Baked into `.opencode/opencode.json` → `permission` | `"<s>_*": "allow"` — OpenCode names MCP tools `<s>_<tool>` |
477
540
 
@@ -573,7 +636,7 @@ bkit ships no default: the setting also hides each person's own connectors (mail
573
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 |
574
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) |
575
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) |
576
- | 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) |
577
640
 
578
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.
579
642
 
@@ -775,7 +838,7 @@ Cells show pin · score · $/task. Deltas are against that column's target. Key
775
838
 
776
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.
777
840
 
778
- 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).
779
842
 
780
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:
781
844
 
@@ -819,7 +882,7 @@ The cloud OpenAI-compatible cells are tool-call-smoked (a `tools:` round-trip re
819
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 |
820
883
  | Cursor | Cursor 2.4+ Agent Skills (similar shape). | `.cursor/skills/` (per docs); `.agents/skills/` referenced via custom routing |
821
884
 
822
- `.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`.
823
886
 
824
887
  ---
825
888
 
@@ -853,7 +916,7 @@ A full test gate runs for minutes, and a gate that waits for the machine-wide te
853
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 |
854
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 |
855
918
 
856
- **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.
857
920
 
858
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.
859
922