@cbartens/bkit 6.0.0 → 6.1.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 (375) hide show
  1. package/.bkit/README.md +154 -151
  2. package/.bkit/core/.agents/context.md +95 -29
  3. package/.bkit/core/.agents/docs.md +17 -15
  4. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
  5. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
  6. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
  7. package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
  8. package/.bkit/core/.agents/rules.md +108 -107
  9. package/.bkit/core/.agents/skills.md +63 -15
  10. package/.bkit/core/.bkit/README.md +154 -151
  11. package/.bkit/core/.bkit/authoring.md +714 -84
  12. package/.bkit/core/.bkit/cli.md +407 -0
  13. package/.bkit/core/.bkit/cloud.md +281 -193
  14. package/.bkit/core/.bkit/comparison.md +43 -41
  15. package/.bkit/core/.bkit/install.md +154 -84
  16. package/.bkit/core/.bkit/jsonl.md +193 -130
  17. package/.bkit/core/.bkit/pipeline.md +114 -114
  18. package/.bkit/core/.bkit/prompts.md +272 -165
  19. package/.bkit/core/.bkit/providers.md +457 -271
  20. package/.bkit/core/.bkit/router.md +69 -0
  21. package/.bkit/core/.bkit/templates.md +529 -256
  22. package/.bkit/core/.bkit/trackers.md +80 -52
  23. package/.bkit/core/.bkit/workflows.md +589 -504
  24. package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
  25. package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
  26. package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
  27. package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
  28. package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
  29. package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
  30. package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
  31. package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
  32. package/.bkit/core/AGENTS.md +5 -73
  33. package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
  34. package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
  35. package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
  36. package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
  37. package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
  38. package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
  39. package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
  40. package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
  41. package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
  42. package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
  43. package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
  44. package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
  45. package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
  46. package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
  47. package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
  48. package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
  49. package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
  50. package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
  51. package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
  52. package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
  53. package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
  54. package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
  55. package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
  56. package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
  57. package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
  58. package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
  59. package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
  60. package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
  61. package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
  62. package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
  63. package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
  64. package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
  65. package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
  66. package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
  67. package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
  68. package/.bkit/core/docs/templates/bkit-plan.md +138 -132
  69. package/.bkit/core/engine/checks/after/auth.ts +40 -37
  70. package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
  71. package/.bkit/core/engine/checks/after/index.ts +12 -2
  72. package/.bkit/core/engine/checks/after/tools.ts +80 -33
  73. package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
  74. package/.bkit/core/engine/checks/before/env.ts +1 -1
  75. package/.bkit/core/engine/checks/before/index.ts +7 -0
  76. package/.bkit/core/engine/checks/before/repo.ts +40 -0
  77. package/.bkit/core/engine/checks/status-holes.ts +916 -123
  78. package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
  79. package/.bkit/core/engine/checks/tips/detect.ts +32 -0
  80. package/.bkit/core/engine/checks/tips/index.ts +47 -6
  81. package/.bkit/core/engine/cli.ts +238 -84
  82. package/.bkit/core/engine/commands/analysis.ts +128 -76
  83. package/.bkit/core/engine/commands/ci/ci.ts +363 -29
  84. package/.bkit/core/engine/commands/ci/pins.ts +172 -0
  85. package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
  86. package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
  87. package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
  88. package/.bkit/core/engine/commands/land.ts +126 -11
  89. package/.bkit/core/engine/commands/lib.ts +303 -6
  90. package/.bkit/core/engine/commands/registry.ts +6 -2
  91. package/.bkit/core/engine/commands/setup/setup.ts +1 -0
  92. package/.bkit/core/engine/commands/stats.ts +91 -35
  93. package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
  94. package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
  95. package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
  96. package/.bkit/core/engine/commands/workflow/context.ts +433 -55
  97. package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
  98. package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
  99. package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
  100. package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
  101. package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
  102. package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
  103. package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
  104. package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
  105. package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
  106. package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
  107. package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
  108. package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
  109. package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
  110. package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
  111. package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
  112. package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
  113. package/.bkit/core/engine/commands/workflow/status.ts +200 -17
  114. package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
  115. package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
  116. package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
  117. package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
  118. package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
  119. package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
  120. package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
  121. package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
  122. package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
  123. package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
  124. package/.bkit/core/engine/install/cloud-env.ts +251 -121
  125. package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
  126. package/.bkit/core/engine/install/manifest.ts +60 -12
  127. package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
  128. package/.bkit/core/engine/install/modules/cloud.ts +3 -3
  129. package/.bkit/core/engine/install/modules/codex.ts +15 -2
  130. package/.bkit/core/engine/install/modules/core.ts +956 -52
  131. package/.bkit/core/engine/install/modules/cursor.ts +6 -6
  132. package/.bkit/core/engine/install/modules/opencode.ts +16 -4
  133. package/.bkit/core/engine/install/template-notes.ts +130 -0
  134. package/.bkit/core/engine/install/version-file.ts +3 -2
  135. package/.bkit/core/engine/install/write.ts +5 -0
  136. package/.bkit/core/engine/ledgers/compact.ts +124 -0
  137. package/.bkit/core/engine/ledgers/journal.ts +291 -0
  138. package/.bkit/core/engine/ledgers/status.ts +160 -9
  139. package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
  140. package/.bkit/core/engine/render/hosts.ts +114 -14
  141. package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
  142. package/.bkit/core/engine/shared/dep-updater.ts +60 -0
  143. package/.bkit/core/engine/shared/egress.ts +1 -1
  144. package/.bkit/core/engine/shared/package-manager.ts +9 -0
  145. package/.bkit/core/engine/shared/settings.ts +92 -17
  146. package/.bkit/core/engine/shared/timeouts.ts +2 -0
  147. package/.bkit/core/engine/tools/cli-doc.ts +111 -0
  148. package/.bkit/core/engine/tools/grammar-density.ts +1 -1
  149. package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
  150. package/.bkit/core/engine/tools/instructions.ts +94 -43
  151. package/.bkit/core/hooks/antigravity-hook.js +25 -10
  152. package/.bkit/core/hooks/gateguard-engine.js +53 -29
  153. package/.bkit/core/hooks/guardrails-shell.js +4 -4
  154. package/.bkit/core/hooks/guardrails-tiers.js +3 -3
  155. package/.bkit/core/hooks/preflight-linear.sh +9 -9
  156. package/.bkit/core/hooks/preflight-rules.sh +8 -0
  157. package/.bkit/core/hooks/readguard-engine.js +29 -10
  158. package/.bkit/core/hooks/session-rules-advisory.js +61 -0
  159. package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
  160. package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
  161. package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
  162. package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
  163. package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
  164. package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
  165. package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
  166. package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
  167. package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
  168. package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
  169. package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
  170. package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
  171. package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
  172. package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
  173. package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
  174. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
  175. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
  176. package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
  177. package/.bkit/core/prompts/bkit-design-generate.md +68 -52
  178. package/.bkit/core/prompts/bkit-design-organise.md +73 -35
  179. package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
  180. package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
  181. package/.bkit/core/prompts/bkit-design-spike.md +54 -47
  182. package/.bkit/core/prompts/bkit-design-update.md +42 -31
  183. package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
  184. package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
  185. package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
  186. package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
  187. package/.bkit/core/prompts/bkit-plan-update.md +70 -52
  188. package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
  189. package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
  190. package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
  191. package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
  192. package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
  193. package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
  194. package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
  195. package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
  196. package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
  197. package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
  198. package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
  199. package/.bkit/core/workflows/bkit-auto.md +53 -30
  200. package/.bkit/core/workflows/bkit-build.md +635 -304
  201. package/.bkit/core/workflows/bkit-debug.md +301 -148
  202. package/.bkit/core/workflows/bkit-design.md +167 -95
  203. package/.bkit/core/workflows/bkit-plan.md +172 -84
  204. package/.bkit/core/workflows/bkit-ship.md +299 -152
  205. package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
  206. package/.bkit/shared/.claude/bkit-cloud.md +12 -10
  207. package/.bkit/shared/.claude/settings.json +3 -0
  208. package/.bkit/shared/.codex/bkit-cloud.md +98 -0
  209. package/.bkit/shared/.codex/hooks.json +20 -0
  210. package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
  211. package/.bkit/shared/.opencode/opencode.json +1 -1
  212. package/.bkit/shared/CLAUDE.md +5 -1
  213. package/.bkit/shared/GEMINI.md +4 -1
  214. package/.bkit/shared/docs/architecture.md +4 -7
  215. package/.bkit/shared/docs/data-schema.md +4 -7
  216. package/.bkit/shared/docs/deployments.md +239 -166
  217. package/.bkit/shared/docs/design.md +11 -12
  218. package/.bkit/shared/docs/noise.md +8 -7
  219. package/.bkit/shared/docs/observability.md +5 -8
  220. package/.bkit/shared/docs/security.md +35 -17
  221. package/.bkit/shared/docs/setup.md +29 -18
  222. package/.bkit/shared/docs/technology.md +3 -6
  223. package/.bkit/shared/docs/testing.md +282 -176
  224. package/.bkit/shared/gitignore +6 -2
  225. package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
  226. package/.bkit/templates/.cursor/Dockerfile +12 -8
  227. package/.bkit/templates/.cursor/environment.json +1 -1
  228. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
  229. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
  230. package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
  231. package/.bkit/templates/.github/renovate.json5 +34 -6
  232. package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
  233. package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
  234. package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
  235. package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
  236. package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
  237. package/.bkit/templates/.husky/pre-commit +2 -2
  238. package/.bkit/templates/.husky/pre-push +95 -35
  239. package/.bkit/templates/.prettierignore +6 -7
  240. package/.bkit/templates/.vale.ini +27 -27
  241. package/.bkit/templates/context/bkit-cloudrun.md +23 -15
  242. package/.bkit/templates/context/bkit-expo.md +70 -52
  243. package/.bkit/templates/context/bkit-github.md +93 -56
  244. package/.bkit/templates/context/bkit-inngest.md +21 -15
  245. package/.bkit/templates/context/bkit-maestro.md +22 -16
  246. package/.bkit/templates/context/bkit-playwright.md +23 -17
  247. package/.bkit/templates/context/bkit-resend.md +12 -10
  248. package/.bkit/templates/context/bkit-sentry.md +30 -20
  249. package/.bkit/templates/context/bkit-serena.md +8 -7
  250. package/.bkit/templates/context/bkit-stripe.md +14 -13
  251. package/.bkit/templates/context/bkit-supabase.md +16 -13
  252. package/.bkit/templates/context/bkit-tavily.md +14 -11
  253. package/.bkit/templates/context/bkit-vercel.md +27 -18
  254. package/.bkit/templates/docs/capabilities.md +15 -14
  255. package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
  256. package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
  257. package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
  258. package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
  259. package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
  260. package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
  261. package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
  262. package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
  263. package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
  264. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
  265. package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
  266. package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
  267. package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
  268. package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
  269. package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
  270. package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
  271. package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
  272. package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
  273. package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
  274. package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
  275. package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
  276. package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
  277. package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
  278. package/.bkit/templates/slop-scan.config.json +9 -2
  279. package/CHANGELOG.md +119 -0
  280. package/README.md +250 -76
  281. package/dist/checks/after/auth.js +36 -33
  282. package/dist/checks/after/ci-yml.js +52 -2
  283. package/dist/checks/after/index.js +12 -4
  284. package/dist/checks/after/tools.js +73 -33
  285. package/dist/checks/before/context-fetch.js +218 -33
  286. package/dist/checks/before/env.js +1 -1
  287. package/dist/checks/before/index.js +6 -2
  288. package/dist/checks/before/repo.js +35 -1
  289. package/dist/checks/status-holes.js +739 -114
  290. package/dist/checks/tips/catalogue.js +59 -17
  291. package/dist/checks/tips/detect.js +30 -0
  292. package/dist/checks/tips/index.js +48 -6
  293. package/dist/cli.js +222 -84
  294. package/dist/commands/analysis.js +77 -53
  295. package/dist/commands/ci/ci.js +302 -25
  296. package/dist/commands/ci/pins.js +142 -0
  297. package/dist/commands/ci/push-gate.js +194 -0
  298. package/dist/commands/install/uninstall.js +23 -27
  299. package/dist/commands/install/upgrade.js +21 -11
  300. package/dist/commands/land.js +126 -10
  301. package/dist/commands/lib.js +244 -5
  302. package/dist/commands/registry.js +6 -2
  303. package/dist/commands/setup/setup.js +1 -0
  304. package/dist/commands/stats.js +69 -30
  305. package/dist/commands/workflow/branches.js +1232 -111
  306. package/dist/commands/workflow/challenge.js +90 -37
  307. package/dist/commands/workflow/completeness.js +97 -0
  308. package/dist/commands/workflow/context.js +371 -51
  309. package/dist/commands/workflow/counters.js +206 -40
  310. package/dist/commands/workflow/decisions.js +60 -17
  311. package/dist/commands/workflow/disk.js +213 -55
  312. package/dist/commands/workflow/fids.js +18 -1
  313. package/dist/commands/workflow/issues.js +6 -0
  314. package/dist/commands/workflow/ledgers.js +372 -21
  315. package/dist/commands/workflow/locks.js +2 -0
  316. package/dist/commands/workflow/plan-blocks.js +78 -14
  317. package/dist/commands/workflow/plans.js +205 -0
  318. package/dist/commands/workflow/prs.js +12 -3
  319. package/dist/commands/workflow/repo.js +6 -0
  320. package/dist/commands/workflow/roadmap.js +50 -17
  321. package/dist/commands/workflow/run-facts.js +23 -28
  322. package/dist/commands/workflow/runs.js +530 -33
  323. package/dist/commands/workflow/runtime.js +3 -0
  324. package/dist/commands/workflow/skills.js +1 -0
  325. package/dist/commands/workflow/status.js +166 -19
  326. package/dist/commands/workflow/step-table.js +61 -29
  327. package/dist/commands/workflow/steps.js +542 -26
  328. package/dist/commands/workflow/summary-findings.js +117 -0
  329. package/dist/commands/workflow/summary.js +154 -41
  330. package/dist/commands/workflow/tasks.js +378 -0
  331. package/dist/commands/workflow/test-blocks.js +231 -0
  332. package/dist/commands/workflow/tests-changed.js +172 -0
  333. package/dist/commands/workflow/tests.js +1013 -321
  334. package/dist/commands/workflow/workflows.js +191 -38
  335. package/dist/commands/workflow/worktrees.js +310 -42
  336. package/dist/install/cloud-env.js +233 -99
  337. package/dist/install/context-ci-workflow.js +85 -0
  338. package/dist/install/manifest.js +57 -12
  339. package/dist/install/modules/antigravity.js +3 -2
  340. package/dist/install/modules/cloud.js +3 -3
  341. package/dist/install/modules/codex.js +12 -2
  342. package/dist/install/modules/core.js +851 -53
  343. package/dist/install/modules/cursor.js +6 -6
  344. package/dist/install/modules/opencode.js +11 -5
  345. package/dist/install/template-notes.js +116 -0
  346. package/dist/install/version-file.js +3 -2
  347. package/dist/ledgers/compact.js +87 -0
  348. package/dist/ledgers/journal.js +233 -0
  349. package/dist/ledgers/status.js +115 -5
  350. package/dist/ledgers/telemetry.js +121 -17
  351. package/dist/render/hosts.js +100 -14
  352. package/dist/shared/bkit-latest.js +26 -4
  353. package/dist/shared/dep-updater.js +49 -0
  354. package/dist/shared/egress.js +1 -1
  355. package/dist/shared/package-manager.js +6 -0
  356. package/dist/shared/settings.js +59 -10
  357. package/dist/shared/timeouts.js +2 -0
  358. package/dist/tools/cli-doc.js +97 -0
  359. package/dist/tools/grammar-density.js +1 -1
  360. package/dist/tools/instructions-sources.js +15 -16
  361. package/dist/tools/instructions.js +83 -39
  362. package/package.json +58 -42
  363. package/.bkit/core/.bkit/lite.md +0 -73
  364. package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
  365. package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
  366. package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
  367. package/dist/commands/workflow/workstreams.js +0 -149
  368. /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
  369. /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
  370. /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
  371. /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
  372. /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
  373. /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
  374. /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
  375. /package/.bkit/templates/scripts/launchd/{ai.bkit.launchd.plist → bkit-launchd.plist} +0 -0
@@ -3,43 +3,48 @@
3
3
  {{BKIT_MANAGED_MARKER}}
4
4
 
5
5
  > [!CAUTION]
6
- > **Purpose:** Authoritative inventory of IDE host differences. Drives install script transform rules. Source-of-truth for "what changes between IDE versions of commands and subagents".
6
+ > **Purpose:** The authoritative inventory of how the IDE hosts differ, and the source of truth for what changes between each host's version of the commands and subagents. The install script's transform rules follow it.
7
7
  >
8
8
  > **Rules:**
9
9
  >
10
- > - Use dense token-efficient phrasing; no filler / hedging / restating; tables > prose, bullets > paragraphs.
11
- > - Describe current state / rules, not reasons / history; state what to do, not why.
12
- > - Check `.agents/docs.md` index first and confirm topic belongs in this doc, not another.
13
- > - Ships to consumers: describe the current setup only. NEVER an internal identifier (tracker issue number, ledger key, review-finding id) and NEVER project history — decisions belong in `docs/decisions.jsonl`, incidents in `docs/knowledge.jsonl`.
14
- > - One row per concern. Update when an IDE adds / changes a feature.
15
- > - Unlisted = identical across hosts; install copies byte-identical.
16
- > - Canonical format = Claude. All transforms = Claude → other.
10
+ > - Follow `.bkit/authoring.md` § All Agent-Read Files and § Docs when you edit this file.
11
+ > - This file ships to every project that installs bkit. Describe the current setup and the trade-offs behind it.
12
+ > - Leave out internal labels, such as tracker issue numbers, ledger keys and review-finding ids, and leave out project history. Decisions go in `docs/decisions.jsonl`, and incidents go in `docs/knowledge.jsonl`.
13
+ > - Give each concern one row.
14
+ > - Update this file when an IDE adds or changes a feature.
15
+ > - A concern not listed here is identical on every host, and install copies its files byte-identical.
16
+ > - Claude's format is the canonical one. Every transform runs from Claude's format to another host's.
17
17
 
18
18
  ## Supported hosts
19
19
 
20
20
  <!-- prettier-ignore -->
21
21
  | Host | Tier | Subagent dir | Command dir | Settings | Hooks | Install |
22
22
  | --- | --- | --- | --- | --- | --- | --- |
23
- | Claude Code | canonical | `.claude/agents/` | `.claude/commands/` | `.claude/settings.json` | `.claude/hooks/` (registered in settings) | `bkit install --claude` |
23
+ | Claude | canonical | `.claude/agents/` | `.claude/commands/` | `.claude/settings.json` | `.claude/hooks/` (registered in settings) | `bkit install --claude` |
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
+ | 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` |
24
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` |
25
- | opencode | additive (opt-in) | `.opencode/agents/` | `.opencode/commands/` | `.opencode/opencode.json` | `.opencode/plugin/bkit-gateguard.js` + `.opencode/plugin/bkit-readguard.js` (tool execute hooks) | `bkit install --opencode=<provider>` |
26
- | Codex CLI | 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` (PreToolUse `apply_patch` / `Bash`, PreCompact, via `.codex/hooks.json`) | `bkit install --codex` |
27
- | Google 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` (PreToolUse `write_to_file` / `replace_file_content` / `view_file` / `run_command`, via `.agents/plugins/bkit/hooks.json`) | `bkit install --antigravity` |
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>` |
28
28
 
29
- **Two axes — host != provider.** **Host** = program reading what bkit writes, identified by its dir (`.claude/`, `.cursor/`, `.opencode/`, `.codex/`). **Provider** = gateway tokens are bought through. Model IDs are per-provider → `prompts.md` § Models = one column per PROVIDER (shared provider = one column, never two). Thinking depth is per-host (field name + ladder set by host config format: `effort:` claude/cursor, a `variant:` field opencode, `model_reasoning_effort` codex) → § Effort = one column per HOST. Neither table grows as hosts x providers.
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
 
31
- **One provider per host = POLICY, not capability.** Nothing technical forces it — Cursor reaches Claude models, so does anything behind OpenRouter. Pin follows cost: each host runs on the gateway whose subscription is already paid. Subscription spent → switch **host**, not provider (the cheap gateway hangs off a different host).
31
+ **Spend order: subscriptions first, metered overflow second.**
32
+
33
+ 1. **Subscriptions** — Claude, Codex, Antigravity and Cursor are paid up front, so spend their included usage first. Each agent gets the vendor model that buys the most work per included token (§ Selecting pins, First-party plan).
34
+ 2. **Overflow** — when a subscription's weekly usage runs out, switch to OpenCode on a metered gateway (default `openrouter`) until the usage resets. There Claude is the yardstick: each agent gets the cheapest model closest to its Claude bar, inside a weekly cap (§ Budget band).
35
+
36
+ **One provider per host = policy, not capability.** Nothing technical forces it: Cursor reaches Claude models, and so does anything behind OpenRouter. The pin follows cost, so each host runs on the gateway whose subscription is already paid. When a subscription is spent, switch the host, not the provider, because the overflow gateway hangs off OpenCode.
32
37
 
33
38
  <!-- prettier-ignore -->
34
39
  | Host | Provider | Why |
35
40
  | --- | --- | --- |
36
- | Claude Code | `anthropic` | Claude subscription = cheapest path to Claude models |
41
+ | Claude | `anthropic` | Claude subscription = cheapest path to Claude models |
42
+ | Codex | `openai` | ChatGPT subscription |
43
+ | Antigravity | `google` | Antigravity free tier / Google subscription — cheapest path to Gemini |
37
44
  | Cursor | `cursor` | Cursor subscription covers its whole catalog |
38
- | Codex CLI | `openai` | ChatGPT subscription |
39
- | Google Antigravity | `google` | Antigravity free tier / Google subscription — cheapest path to Gemini |
40
- | opencode | **pick one**: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | no subscription — BYO key, so the choice is yours |
45
+ | OpenCode | pick one: `openrouter`, `ollama`, `opencode-zen`, `opencode-go` | overflow host — metered BYO key, runs when subscription usage is spent |
41
46
 
42
- Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-key host → pluggable, flag names the provider (`--opencode=<provider>`). Per-model deviation → consumer `## Model Overrides` below `bkit:end`; 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`. There is no provider override.
43
48
 
44
49
  ### Codex CLI — three deviations
45
50
 
@@ -47,59 +52,59 @@ Subscription-bearing host → pinned, nullary flag (`--claude`, `--codex`). BYO-
47
52
  | Concern | On Codex |
48
53
  | --- | --- |
49
54
  | Agent files | `.codex/agents/*.toml` (TOML, not markdown). Required: `name`, `description`, `developer_instructions`. Pin + rung: `model`, `model_reasoning_effort`. |
50
- | Workflows = SKILLS, invoked `$bkit-design` | no project-scoped command surface — custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). This path is Codex's; Antigravity ships its own skills in a plugin (`.agents/plugins/bkit/skills/`). |
51
- | `tools:` not enforced | No per-agent tool allowlist upstream; `sandbox_mode` cannot substitute — every bkit agent is write-capable, so all would be `workspace-write`. Each agent gets the full built-in tool set regardless of declared `tools:`. GateGuard still gates, as everywhere. |
55
+ | Workflows = skills, invoked `$bkit-design` | no project-scoped command surface: custom prompts are `~/.codex/prompts` only, not repo-shared, deprecated for skills (upstream declined repo-scoped prompts). bkit renders `.agents/skills/bkit-<workflow>/SKILL.md`, on Codex's skill path (`$REPO_ROOT/.agents/skills`). This path is Codex's; Antigravity ships its own skills in a plugin (`.agents/plugins/bkit/skills/`). |
56
+ | `tools:` not enforced | No per-agent tool allowlist upstream. `sandbox_mode` cannot substitute, because every bkit agent is write-capable, so all would be `workspace-write`. Each agent gets the full built-in tool set regardless of declared `tools:`. GateGuard still gates, as everywhere. |
52
57
 
53
- > **GateGuard needs the `.codex/` layer TRUSTED.** Codex loads project-local hooks only once trusted. Until then the hook is installed and never fires — present, proving nothing. Same for `bkit-guardrails.cjs`.
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`.
54
59
  >
55
- > **Codex cannot prompt.** It parses `permissionDecision: "ask"` but does not implement it — an ask is recorded as an error and the call proceeds. `bkit-guardrails.cjs` therefore blocks the `deny` tier for real and emits the `ask` tier as advisory `additionalContext`: the gate fires and informs, it cannot stop the command. Every ask-tier command is already PROHIBITED in all five workflow headers, so no bkit workflow reaches one. Asserted in `.bkit/core/engine/install/modules/index.integration.test.ts`.
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.
56
61
 
57
- ### Google Antigravity — installs as a workspace plugin
62
+ ### Antigravity — installs as a workspace plugin
58
63
 
59
64
  <!-- prettier-ignore -->
60
65
  | Concern | On Antigravity |
61
66
  | --- | --- |
62
- | Install layout | the whole host is a workspace **plugin** at `.agents/plugins/bkit/` (`plugin.json` + `skills/` + `agents/` + `hooks.json` + `hooks/`) — Antigravity's own packaging surface, activated per project. `.agents/` root stays the dedicated Codex install. |
63
- | Workflows = SKILLS at `.agents/plugins/bkit/skills/bkit-<workflow>/SKILL.md` | Antigravity auto-discovers a workspace plugin's `skills/`. Codex's workflow skills stay at `.agents/skills/bkit-*/`; with both hosts installed Antigravity's selector lists both sets (accepted; `antigravity-codex-skill-overlap` advisory names which to pick). |
67
+ | Install layout | the whole host is a workspace plugin at `.agents/plugins/bkit/` (`plugin.json` + `skills/` + `agents/` + `hooks.json` + `hooks/`) — Antigravity's own packaging surface, activated per project. `.agents/` root stays the dedicated Codex install. |
68
+ | Workflows = skills at `.agents/plugins/bkit/skills/bkit-<workflow>/SKILL.md` | Antigravity auto-discovers a workspace plugin's `skills/`. Codex's workflow skills stay at `.agents/skills/bkit-*/`; with both hosts installed Antigravity's selector lists both sets (accepted; `antigravity-codex-skill-overlap` advisory names which to pick). |
64
69
  | Prompt files + no native subagent tool | prompts at `.agents/plugins/bkit/agents/*.md` — frontmatter `name`/`description`, model pin from § Models `Google` column, `effort` from § Effort `Antigravity` column, `tools:` respelled to Antigravity tool names. The orchestrator loads each with `view_file` and runs it in-session; isolated runs use `run_command` (`agy`). `**Subagent:** @name` respells to `` `view_file` `.agents/plugins/bkit/agents/name.md` `` rather than a `/name` slash command. |
65
70
 
66
71
  > **Antigravity tool names differ from Claude's.** `Read`→`view_file`, `Write`→`write_to_file`, `Edit`→`replace_file_content`, `Bash`→`run_command`, `Grep`→`grep_search`, `Glob`→`list_dir`, `WebSearch`→`search_web`, `WebFetch`→`read_url`. `mcp__<server>__<tool>` keeps its spelling. `applyAntigravityPrompt` / `antigravityToolsBlock` (`.bkit/core/engine/render/hosts.ts`) apply the map at render.
67
72
  >
68
- > **GateGuard + ReadGuard + guardrails wired from `.agents/plugins/bkit/hooks.json`** (PreToolUse on `write_to_file` / `replace_file_content` / `view_file` / `run_command`). Same fail-open engines as the other hosts on Antigravity's own contract, live-verified on the agy CLI: stdin `{ conversationId, toolCall: { name, args }, workspacePaths }`, stdout `{ decision, reason }`. Only a `deny`'s reason reaches the model, so every advisory denies the call once with the advisory as the reason and lets the identical retry through; the guardrails deny tier blocks every time; its ask tier is Antigravity's own `ask`. Guardrails also gates `view_file` secret reads (§ Permissions / auto-approve). A `PreInvocation` entry in `hooks.json` stops every hook in the file from firing — bkit registers none. Plugin hook commands run with the plugin dir (`.agents/plugins/bkit/`) as cwd, so each command tries `hooks/<file>` first, then `.agents/plugins/bkit/hooks/<file>`.
73
+ > **GateGuard + ReadGuard + guardrails wired from `.agents/plugins/bkit/hooks.json`** (PreToolUse on `write_to_file` / `replace_file_content` / `view_file` / `run_command`). They run the same fail-open engines as the other hosts, on Antigravity's own contract, live-verified on the agy CLI: stdin `{ conversationId, toolCall: { name, args }, workspacePaths }`, stdout `{ decision, reason }`. Only a `deny`'s reason reaches the model, so every advisory denies the call once, with the advisory as the reason, and lets the identical retry through. The guardrails deny tier blocks every time, and its ask tier is Antigravity's own `ask`. Guardrails also gates `view_file` secret reads (§ Permissions / auto-approve). A `PreInvocation` entry in `hooks.json` stops every hook in the file from firing, so bkit registers none. Plugin hook commands run with the plugin dir (`.agents/plugins/bkit/`) as cwd, so each command tries `hooks/<file>` first, then `.agents/plugins/bkit/hooks/<file>`.
69
74
 
70
- **Explicit host axis (no implicit full):** `bkit install` requires >=1 module flag or `--tracker=` — bare `bkit install` errors. `--tracker=` re-renders every installed host. Every host explicit; hosts compose: `bkit install --claude --cursor --opencode=opencode-zen` installs all three (+ implicit core). `--opencode` cannot render without `=<provider>` (strict allowlist). Switch providers: re-run install. All hosts render from `.bkit/`; run state in `status.jsonl` + plan docs + tracker (never host session) — phase/resumed run moves across hosts/providers mid-feature with identical gates + per-agent pins: hit limit on one, continue on another. `bkit status` → installed hosts + active providers; `bkit doctor` → credentials + tool reachability.
75
+ **Explicit host axis (no implicit full):** `bkit install` requires at least 1 module flag or `--tracker=`, and a bare `bkit install` errors. `--tracker=` re-renders every installed host. Every host is named explicitly, and hosts compose: `bkit install --claude --cursor --opencode=opencode-zen` installs all three, plus the implicit core. `--opencode` cannot render without `=<provider>` (strict allowlist). To switch providers, re-run install. All hosts render from `.bkit/`, and run state lives in `status.jsonl`, the plan docs and the tracker, never in a host session, so a phase or a resumed run can move across hosts or providers mid-feature, with identical gates and per-agent pins: hit the limit on one, and continue on another. `bkit status` shows the installed hosts and the active providers, and `bkit doctor` checks credentials and tool reachability.
71
76
 
72
- **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` + opencode in the IDE's integrated terminal = every agent pin, GateGuard and the full workflow on OpenRouter while editing in Cursor. Supported path when the Claude subscription is spent.
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.
73
78
 
74
- > **Curated-column status (COMPLETE).** All four allowlisted providers (`openrouter`, `ollama`, `opencode-zen`, `opencode-go`) ship curated per-agent model pins in `prompts.md` § Models → install ready-to-run. Both OpenAI-compatible providers + both opencode gateways curated after live catalog probe + per-model tool-calling smoke (`tools:` chat/completions round-trip emitting `tool_calls`; `/models` alone != proof). **opencode catalogs = models.dev, not `/zen/v1/models`** — REST endpoint returns Zen-only; cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`, …); models.dev source of truth (`opencode` = Zen, `opencode-go` = Go). `opencode-go` curated from models.dev/Go endpoint; prefer pins within Go 5h window; `opencode-zen` existence-validated via models.dev. See § Models for live-probe recipe + 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 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.
75
80
 
76
- **Additive multi-provider install:** `bkit install --opencode=<provider>` additive — second provider adds block to `opencode.json`, keeps first. Agent frontmatter (`model:`) re-renders to last-installed (active) provider; other blocks stay for interactive switch/overrides. Installed providers → `bkit.providers.opencode.installed: string[]` in `package.json`; active → `bkit.providers.opencode.default`. `bkit status` lists all, marks active, and prints the `model:` pins read from `.opencode/agents/*.md`; `bkit doctor` checks all credentials. Remove one: `bkit uninstall --opencode=<provider>` (surgical — block + array; if active removed, the first remaining provider becomes active and agents/commands re-render to its pins, so `bkit check` stays green). `bkit uninstall --opencode` (bare) tears down entire opencode host.
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.
77
82
 
78
- New host — row above + `run<Host>Module` (`.bkit/core/engine/install/modules/<host>.ts`) + manifest block (`.bkit/core/engine/install/manifest.ts`) + `.bkit/core/.<host>/hooks/` (the host config JSON in `.bkit/shared/.<host>/`) + GateGuard case in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts` + ReadGuard case in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`. New provider = entry in `OPENCODE_PROVIDERS` (`.bkit/core/engine/shared/egress.ts`); `tsc` then demands its `OPENCODE_PROVIDER_DEFAULTS` and `GATEWAY_COLUMN` (`.bkit/core/engine/render/models.ts`) entries. Also needs a curated `prompts.md` § Models column.
83
+ 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.
79
84
 
80
85
  ---
81
86
 
82
87
  ## macOS GUI-isolation — `bkit cursor` / `bkit opencode`
83
88
 
84
- **Root cause:** macOS GUI apps (Dock/Finder/Spotlight) run under `launchd` — **do not** inherit login-shell env. `direnv` exports from `.bkit/.env` stay shell-only. Token placeholders (`${BKIT_GH_TOKEN}` in `.cursor/mcp.json`, `{env:BKIT_OPENCODE_API_KEY}` in `.opencode/opencode.json`) resolve empty → MCP auth failures.
89
+ **Root cause:** macOS GUI apps (Dock / Finder / Spotlight) run under `launchd`, and they do not inherit the login shell's env. `direnv` exports from `.bkit/.env` stay in the shell. Token placeholders (`${BKIT_GH_TOKEN}` in `.cursor/mcp.json`, `{env:BKIT_OPENCODE_API_KEY}` in `.opencode/opencode.json`) then resolve empty, and MCP auth fails.
85
90
 
86
- **Shared service env (opencode):** `{env:…}` in `.opencode/opencode.json` resolves in OpenCode's background service — machine-global, one per user, env fixed at service start. Repo-local direnv `.env` is invisible (one repo's `apps/web/.env.local` never reaches another); service env = union of every repo's MCP tokens. Add / rotate a token → source it, then `opencode service restart`.
91
+ **Shared service env (OpenCode):** `{env:…}` in `.opencode/opencode.json` resolves in OpenCode's background service. That service is machine-global, one per user, and its env is fixed when the service starts. A repo-local direnv `.env` is invisible to it (one repo's `apps/web/.env.local` never reaches another), and the service env is the union of every repo's MCP tokens. To add or rotate a token, source it, then run `opencode service restart`.
87
92
 
88
- **Fix — launcher verbs:** `bkit cursor` / `bkit opencode` exec app binary with `.bkit/.env` merged into child env. Dynamic, per-repo, zero global state.
93
+ **Fix — launcher verbs:** `bkit cursor` / `bkit opencode` exec the app binary with `.bkit/.env` merged into the child env. The fix is dynamic and per-repo, and it keeps no global state.
89
94
 
90
95
  ```
91
96
  bkit cursor # /Applications/Cursor.app/Contents/MacOS/Cursor
92
97
  bkit opencode # /Applications/opencode.app/Contents/MacOS/opencode
93
98
  ```
94
99
 
95
- - **Quit first.** Running instance keeps launch-time env; re-exec required.
100
+ - **Quit first.** A running instance keeps its launch-time env, so the app must be exec'd again.
96
101
  - **Binary override:** `BKIT_CURSOR_BIN=<path>` / `BKIT_OPENCODE_BIN=<path>` for non-standard paths.
97
- - **Cursor:** passes repo `cwd` as positional arg.
98
- - **opencode:** no positional arg; reads `opencode.json` from `cwd`.
102
+ - **Cursor:** the verb passes the repo `cwd` as a positional argument.
103
+ - **OpenCode:** the verb passes no positional argument, and OpenCode reads `opencode.json` from `cwd`.
99
104
 
100
- **`bkit doctor` check:** reports `.bkit/.env` keys with non-empty file value but absent from `process.env` (= Dock/Finder session); advisory → `bkit cursor` / `bkit opencode`.
105
+ **`bkit doctor` check:** reports each `.bkit/.env` key that has a non-empty value in the file but is absent from `process.env`, which marks a Dock / Finder session. Its advisory points to `bkit cursor` / `bkit opencode`.
101
106
 
102
- **launchctl fallback (opt-in, not recommended):** exposes key to EVERY app in the login session (not only the intended one; not persistent across reboots). Manual re-run after restart + manual rotation/removal — prefer launcher verbs.
107
+ **launchctl fallback (opt-in, not recommended):** it exposes the key to every app in the login session, not only the intended one, and the key does not persist across reboots. It needs a manual re-run after each restart, and manual rotation and removal, so prefer the launcher verbs.
103
108
 
104
109
  ```bash
105
110
  launchctl setenv BKIT_GH_TOKEN "$BKIT_GH_TOKEN"
@@ -107,7 +112,7 @@ launchctl setenv BKIT_OPENCODE_API_KEY "$BKIT_OPENCODE_API_KEY"
107
112
  # then relaunch from Dock — values survive until next reboot
108
113
  ```
109
114
 
110
- Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) with one `setenv` per token. Same rotation caveat.
115
+ The persistent variant is a `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) with one `setenv` per token. It has the same rotation caveat.
111
116
 
112
117
  ---
113
118
 
@@ -116,19 +121,19 @@ Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) wi
116
121
  <!-- prettier-ignore -->
117
122
  | Host | Tool name | Prefix | Example |
118
123
  | --- | --- | --- | --- |
119
- | Claude | `Agent` | `@` | `@bkit-build-plan-execute` invoked via `Agent` tool |
120
- | Cursor | `Task` | `/` | `/bkit-build-plan-execute` invoked via `Task` tool |
121
- | opencode | `/` (slash command) | `/` | `/bkit-build-plan-execute` invoked via opencode slash command |
122
- | Antigravity | `view_file` (in-session prompt load) | `.agents/plugins/bkit/agents/` | `view_file` `.agents/plugins/bkit/agents/bkit-build-plan-execute.md` |
124
+ | Claude | `Agent` | `@` | `@bkit-build-plan-tasks` invoked via `Agent` tool |
125
+ | Antigravity | `view_file` (in-session prompt load) | `.agents/plugins/bkit/agents/` | `view_file` `.agents/plugins/bkit/agents/bkit-build-plan-tasks.md` |
126
+ | Cursor | `Task` | `/` | `/bkit-build-plan-tasks` invoked via `Task` tool |
127
+ | OpenCode | `/` (slash command) | `/` | `/bkit-build-plan-tasks` invoked via OpenCode slash command |
123
128
 
124
129
  **Transform (Claude → Cursor, command bodies):**
125
130
 
126
131
  - Replace literal `` `Agent` tool `` with `` `Task` tool ``.
127
132
  - Replace `using \`Agent\` tool`with`using \`Task\` tool`.
128
- - Replace literal `` `Skill` tool `` with `` `Task` tool `` (slash-command — Cursor `Task` covers subagent + slash; Claude splits `Agent` + `Skill`).
133
+ - Replace literal `` `Skill` tool `` with `` `Task` tool `` (for slash commands: Cursor's `Task` covers both subagents and slash commands, where Claude splits them into `Agent` and `Skill`).
129
134
  - Replace `using \`Skill\` tool`with`using \`Task\` tool`.
130
- - Replace `@<name>` with `/<name>` for kebab-case identifiers, **only inside `**Subagent:**` lines and protocol description block**. Don't touch `@` elsewhere (anchors, email, npm scopes).
131
- - Subagent body files lack invocation phrasing — no body transform.
135
+ - Replace `@<name>` with `/<name>` for kebab-case identifiers, only inside `**Subagent:**` lines and the protocol description block. Leave `@` alone everywhere else (anchors, email, npm scopes).
136
+ - Subagent body files hold no invocation phrasing, so they get no body transform.
132
137
 
133
138
  ---
134
139
 
@@ -137,69 +142,69 @@ Persistent variant: `RunAtLoad` LaunchAgent plist (`~/Library/LaunchAgents/`) wi
137
142
  ### Frontmatter
138
143
 
139
144
  <!-- prettier-ignore -->
140
- | Field | Claude | Cursor | opencode | Notes |
145
+ | Field | Claude | Cursor | OpenCode | Notes |
141
146
  | --- | --- | --- | --- | --- |
142
147
  | `name` | required | required | required | kebab-case, must match filename. Identical. |
143
148
  | `description` | required | required | required | Identical. |
144
- | `effort` | required (`low` / `medium` / `high` / `xhigh` / `max` — last two model-gated, Opus-only on current models) | not supported | emitted as a separate `variant:` field | Drop on Cursor. `applyOpencodeAgent` reads the § Effort **OpenCode** column and writes it to `variant:` (not a `#`-suffix on the model — 1.x keeps the suffix in its model id and fails lookup); the OpenCode column ceilings out, so `medium` / `high` / `xhigh` / `max`→`max`, `low`→`none`. The **ollama** gateway omits `variant:` entirely: its provider builds models with no variants, so any variant there is a hard 2.0 error. |
145
- | `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_*`). |
146
- | `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and opencode. |
147
- | `maxTurns` | required | not supported | not supported | Drop on Cursor and opencode. |
148
- | `autoCompactWindow` | `300000` on every `bkit-*` agent | not supported | not supported | Drop on Cursor, opencode, Codex, Antigravity — § Context compaction. |
149
- | `model` | required (explicit Claude model ID — see `prompts.md` § Frontmatter Conventions effort→model mapping) | required | required (provider-prefixed, e.g. `openrouter/moonshotai/kimi-k3`) | Pinned per-agent. Claude locks model. Cursor drives runner via T3. opencode: `<provider>/<model-id>` (see `prompts.md` § Models, columns `OpenRouter` / `Ollama` / …). |
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. |
150
+ | `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
+ | `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and OpenCode. |
152
+ | `maxTurns` | required | not supported | not supported | Drop on Cursor and OpenCode. |
153
+ | `autoCompactWindow` | `300000` on every `bkit-*` agent | not supported | not supported | Drop on Codex, Antigravity, Cursor, OpenCode — § Context compaction. |
154
+ | `model` | required (explicit Claude model ID — see `prompts.md` § Frontmatter Conventions effort→model mapping) | required | required (provider-prefixed, e.g. `openrouter/moonshotai/kimi-k3`) | Pinned per-agent. Claude locks model. Cursor drives runner via T3. OpenCode: `<provider>/<model-id>` (see `prompts.md` § Models, columns `OpenRouter` / `Ollama` / …). |
150
155
  | `readonly` | not supported (use `tools` allowlist) | optional boolean | not supported | Cursor: derive from `tools` (true if no `Edit`/`Write`/`Bash`). |
151
156
  | `is_background` | not supported | optional boolean (Cursor 2.4+) | not supported | Default false. Reserve for future opt-in on parallelisable subagents. |
152
- | `reasoningEffort` | not a frontmatter field (use `effort`) | not supported | not a field — OpenCode carries effort as a `variant:` field | Was opencode-native through 1.x. `applyOpencodeAgent` now emits `variant: <name>` (1.x reads it natively; 2.0 joins `model` + `variant` internally). A `#`-suffix on the `model` pin breaks 1.x and hard-errors on 2.0 when the model exposes no such variant. |
157
+ | `reasoningEffort` | not a frontmatter field (use `effort`) | not supported | not a field — OpenCode carries effort as a `variant:` field | `applyOpencodeAgent` emits `variant: <name>` (1.x reads it natively; 2.0 joins `model` + `variant` internally). A `#`-suffix on the `model` pin breaks 1.x and hard-errors on 2.0 when the model exposes no such variant. |
153
158
 
154
159
  ### Body
155
160
 
156
- Identical across hosts. Process steps, verdict/findings (`## Verdict` / `## Findings`), `Read:` / `Write:` paths, `> ⛔ STOP` — unchanged. No transform.
161
+ The body is identical on every host. Process steps, verdict and findings (`## Verdict` / `## Findings`), `Read:` / `Write:` paths and `> ⛔ STOP` stay unchanged, with no transform.
157
162
 
158
- Cursor model assignment: § Models below — per-agent lookup, not effort-tier derived.
163
+ Cursor model assignment: § Models below. It is a per-agent lookup, not derived from the effort tier.
159
164
 
160
165
  ---
161
166
 
162
167
  ## Models
163
168
 
164
- > **Effort vs model — different mechanisms.** Claude: `effort: low|medium|high|xhigh` = thinking-budget on pinned model. Cursor: explicit `model:` per agent; native-pool diversity (`cursor-grok-4.5-high` / `composer-2.5` — no API-pool defaults). **Per-agent model assignment canonical**; derive Cursor `model` from `prompts.md` § Models, not `effort` alone.
169
+ > **Effort vs model — different mechanisms.** On Claude, `effort: low|medium|high|xhigh` sets the thinking budget on the pinned model. On Cursor, each agent has an explicit `model:`, and the agents use a diversity of native-pool models (`cursor-grok-4.5-high` / `composer-2.5`, with no API-pool defaults). The per-agent model assignment is canonical: derive Cursor's `model` from `prompts.md` § Models, not from `effort` alone.
165
170
 
166
171
  ### Cursor model catalog
167
172
 
168
- **Pinned selections canonical in `prompts.md`** (§ Models `Cursor` column + § Orchestrators) — not here. Cursor set churns; use pull recipe below.
173
+ 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.
169
174
 
170
- > **Default install = first-party pool only.** Shipped Cursor pins are **`cursor-grok-4.5-high`** + **`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. **Have API credits and want Opus back?** Paste the ready-to-use Opus override block in `prompts.md` § Model Overrides (maps every Claude-opus-tier agent → `claude-opus-5-thinking-high`; `/v0/models` has no Opus 5.5 ID). Sonnet-tier override is `claude-sonnet-5-thinking-high` (Sonnet 5, not 5.5) or `gpt-5.6-sol-high`. Then `bkit install --cursor`. 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. **No `cursor-grok-4.7`.**
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`.
171
176
 
172
177
  Tier guidance:
173
178
 
174
- - **`composer-2.5`** ($) — **default.** Fast/cheap: build executors, utilities, `/build` + `/ship` orchestrators. First-party pool.
175
- - **`cursor-grok-4.5-high`** ($$) — **default.** Depth slots, synthesizers, parallel diversity (design/plan/debug orchestrators + former Opus-tier agents). First-party pool (Cursor + SpaceXAI); Coding Agent Index parity with GPT-5.5 at lower per-task cost. `-fast` variant exists.
176
- - **`claude-opus-5-thinking-high`** ($$$) — **override only.** Deep review / audit / synthesis when API credits remain. `/v0/models` has Opus 5, not Opus 5.5 (`claude-opus-5-5` is the Claude pin). `-fast` exists. API pool — burns credits; pin via § Model Overrides, never as shipped default.
177
- - **`claude-sonnet-5-thinking-high`/`-xhigh`** ($$$) — **override only.** Sonnet 5 on the API pool. Not a shipped default. No Sonnet 5.5 ID.
178
- - **`gpt-5.*`** ($$$) — **override only.** API-pool diversity hedge (`gpt-5.6-sol-high`, …). Not pinned.
179
- - **`claude-fable-5-thinking-high`/`-xhigh`** ($$$$) — **override only.** Fable 5. Available, not adopted as default (see `prompts.md` § Effort → Claude model mapping). No Fable 5.1 ID on `/v0/models`.
179
+ - **`composer-2.5`** ($) — default. Fast and cheap: build executors, utilities, and the `/build` and `/ship` orchestrators. First-party pool.
180
+ - **`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
+ - **`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.
183
+ - **`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`.
180
185
 
181
- Cloud Agents API: `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"` (agent-specific API key — general keys can HTTP 500 on `POST /v0/agents`). **Verify before install — Cursor models churn.** Probed 2026-10-06: first-party `cursor-grok-4.5-high` + `composer-2.5`; no Grok 4.7; no Opus 5.5 / Sonnet 5.5. Sonnet 5 thinking IDs are present and stay opt-in. Build/ship orchestrators use `composer-2.5`.
186
+ 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`.
182
187
 
183
188
  > [!NOTE]
184
- > **Native-default Cursor pins.** Defaults are first-party only (`cursor-grok-4.5-high` / `composer-2.5`) so zero API credits still runs the harness. API-pool IDs remain in the live `/v0/models` catalog for manual override. Residual: IDE **subagent-runner** != Cloud Agents API; per-subagent dispatch via `Task` not empirically smoke-tested — confirm one dispatch per model ID before full validation.
189
+ > **Native-default Cursor pins.** The defaults are first-party only (`cursor-grok-4.5-high` / `composer-2.5`), so the harness still runs with zero API credits. API-pool IDs remain in the live `/v0/models` catalog for manual override. One gap remains: the IDE subagent-runner != the Cloud Agents API, and per-subagent dispatch via `Task` has not been smoke-tested in practice. Confirm one dispatch per model ID before full validation.
185
190
  >
186
- > **Claude opus tier pins `claude-opus-5-5`.** Sonnet tier pins `claude-sonnet-5-5`. Both are 1M context, $4/$20 and $2/$10 per MTok. Haiku tier pins `claude-haiku-5-5` — 1M context, $0.10/$0.50 per MTok up to 100K-token prompts, $0.50/$2.50 above. LiveBench scores the 5.5 pins too, but the opus and sonnet targets stay at `claude-opus-5` **65.2** / `claude-sonnet-5` **59.4** — § Agentic-coding parity board says why. Cursor's `/v0/models` catalog lists `claude-opus-5-thinking-high` / `-fast` and `claude-sonnet-5-thinking-high` / `-xhigh`, not the 5.5 IDs. Cursor defaults stay on native models per the native-only policy above.
191
+ > **Claude opus tier pins `claude-opus-5-5`.** The sonnet tier pins `claude-sonnet-5-5`. Both have a 1M context, at $4/$20 and $2/$10 per MTok. The haiku tier pins `claude-haiku-5-5`: 1M context, $0.10/$0.50 per MTok for prompts up to 100K tokens, and $0.50/$2.50 above. The targets are the 5.5 scores on the 2.0 board, `claude-opus-5-5` 72.8 and `claude-sonnet-5-5` 63.4, with no 5.0 bridging. Cursor's `/v0/models` catalog lists `claude-opus-5-thinking-high` / `-fast` and `claude-sonnet-5-thinking-high` / `-xhigh`, not the 5.5 IDs. The Cursor defaults stay on native models, under the native-only policy above.
187
192
 
188
193
  ### Per-subagent model assignment
189
194
 
190
- **Lives in `.bkit/prompts.md`** (per-agent metadata with descriptions, effort/maxTurns rationale, tool patterns).
195
+ The per-subagent model assignment lives in `.bkit/prompts.md`, with the per-agent metadata: descriptions, the effort / maxTurns rationale and tool patterns.
191
196
 
192
- `prompts.md`: one row per agent: `name | Cursor model | Claude effort | role hint`. Canonical for Cursor frontmatter rewrite (T3); `.bkit/core/engine/audits/workflows/models-table-parity.test.ts` checks it against the prompt frontmatter.
197
+ `prompts.md` has one row per agent: `name | Cursor model | Claude effort | role hint`. It is canonical for the Cursor frontmatter rewrite (T3), and `.bkit/core/engine/audits/workflows/models-table-parity.test.ts` checks it against the prompt frontmatter.
193
198
 
194
199
  ### Per-workflow (orchestrator) model
195
200
 
196
- Orchestrator model selection (per workflow, every provider) canonical in **`prompts.md` § Orchestrators** — not duplicated here. Orchestrators use **session model** (commands lack frontmatter): Claude → `/model` before invoke; Cursor → workflow launch (Cloud Agent config / GH Action). Subagent `model:` pins independent — Opus-tier subagents stay pinned regardless of orchestrator. Reasoning-depth (`medium` default) + inlining-drift escalation in `prompts.md` § Orchestrators.
201
+ The orchestrator model for each workflow, on every provider, is canonical in `prompts.md` § Orchestrators, and is not repeated here. Orchestrators run on the session model, because command files have no frontmatter. On Claude, set it with `/model` before invoking the workflow. On Cursor, set it at workflow launch (Cloud Agent config / GH Action). Subagent `model:` pins are independent, so Opus-tier subagents stay pinned whatever the orchestrator runs on. Reasoning depth (default `medium`) and inlining-drift escalation are in `prompts.md` § Orchestrators.
197
202
 
198
203
  ### Cursor model label IDs
199
204
 
200
- Dashboard label-based routing.
205
+ These are the IDs that Cursor uses to route by dashboard label.
201
206
 
202
- > **Stale-risk:** dashboard label-routing UUIDs — distinct from `/v0/models` API IDs; may lag pins. Re-pull from Cloud dashboard before label routing. Per-subagent `model:` frontmatter uses API model-ID string, not these UUIDs.
207
+ > **Stale-risk:** these dashboard label-routing UUIDs are distinct from the `/v0/models` API IDs, and they may lag the pins. Re-pull them from the Cloud dashboard before routing by label. Per-subagent `model:` frontmatter uses the API model-ID string, not these UUIDs.
203
208
 
204
209
  <!-- prettier-ignore -->
205
210
  | Label | ID |
@@ -217,16 +222,16 @@ Dashboard label-based routing.
217
222
 
218
223
  ### Architectural note — `readonly` reconciled
219
224
 
220
- **Decision:** Cursor **never emits `readonly:`**. Subagents write directly on both hosts, matching canonical Claude command shape. Cursor subagents have full tool access: Cursor CLI 2026.10.01 ignores the `tools:` allowlist (measured).
225
+ **Decision:** Cursor never emits `readonly:`. Subagents write directly on both hosts, matching the canonical Claude command shape. Cursor subagents have full tool access: Cursor CLI 2026.10.01 ignores the `tools:` allowlist (measured).
221
226
 
222
- **Implementation:** T3 in `.bkit/core/engine/render/hosts.ts` emits only `name` / `description` / `model` — no `readonly:`. Generated `.cursor/agents/*.md` confirm zero `readonly:` lines.
227
+ **Implementation:** T3 (`applyT3` in `.bkit/core/engine/render/hosts.ts`) emits `name`, `description`, `model`, `effort` when the agent sets one, and the `tools:` block unchanged, with no `readonly:`. The generated `.cursor/agents/*.md` files confirm zero `readonly:` lines.
223
228
 
224
- **Trade-off accepted:** Cursor per-agent runtime safety → tool-allowlist sandboxing once `tools:` lands. Canonical command bodies byte-identical-shape; outputs identical.
229
+ **Trade-off accepted:** per-agent runtime safety on Cursor is left to tool-allowlist sandboxing. `tools:` is passed through, but Cursor does not enforce it. The canonical command bodies keep a byte-identical shape, and the outputs are identical.
225
230
 
226
231
  **Discarded options** (record-only):
227
232
 
228
- - Inject orchestrator-write logic into `.cursor/commands/` during T2 — high body-transform divergence.
229
- - Keep `readonly: true`, document runtime divergence — outputs match, mechanism differs, per-host debugging cost.
233
+ - Inject orchestrator-write logic into `.cursor/commands/` during T2: high body-transform divergence.
234
+ - Keep `readonly: true` and document the runtime divergence: the outputs match, but the mechanism differs, at a per-host debugging cost.
230
235
 
231
236
  ---
232
237
 
@@ -238,37 +243,37 @@ Dashboard label-based routing.
238
243
  | Host | Frontmatter | Notes |
239
244
  | --- | --- | --- |
240
245
  | Claude | `description:` (single field) | Surfaces in slash-command picker. |
241
- | Cursor | **none** | Per current Cursor docs, command files are plain markdown. Frontmatter tolerated/ignored on legacy files but not part of spec. |
246
+ | Cursor | none | Per current Cursor docs, command files are plain markdown. Frontmatter tolerated / ignored on legacy files but not part of spec. |
242
247
 
243
- **Transform (Claude → Cursor, command files):** replace the YAML frontmatter block with its `description:` value as a plain first line (Cursor shows a command file's literal first line as its picker/hover description, and does not read frontmatter). No `description:` key → plain strip.
248
+ **Transform (Claude → Cursor, command files):** replace the YAML frontmatter block with its `description:` value as a plain first line (Cursor shows a command file's literal first line as its picker / hover description, and does not read frontmatter). With no `description:` key, the transform only strips the block.
244
249
 
245
250
  ### Body
246
251
 
247
- - Subagent invocation phrasing — § Subagent invocation transform above.
248
- - Else (tracker MCP, `git`, `gh`, `pnpm`, steps, `Failure Path`, gates, status.jsonl/lock) identical.
252
+ - Subagent invocation phrasing: § Subagent invocation transform above.
253
+ - Everything else (tracker MCP, `git`, `gh`, `pnpm`, steps, `Failure Path`, gates, status.jsonl/lock) is identical.
249
254
 
250
255
  ### Slash-command activation
251
256
 
252
- Both hosts: `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.). Identical UX.
257
+ Both hosts run a command as `/<filename-without-ext>` (`/bkit-build`, `/bkit-plan`, etc.), with identical UX.
253
258
 
254
259
  ---
255
260
 
256
261
  ## Guardrails
257
262
 
258
- Per-action gates, all five hosts, subagents included. Overview only; per-host encoding → § Hooks, § Permissions / auto-approve.
263
+ Per-action gates on all five hosts, subagents included. This section is an overview only. The per-host encoding is in § Hooks and § Permissions / auto-approve.
259
264
 
260
265
  <!-- prettier-ignore -->
261
266
  | Guard | Trigger | Effect | Enforcement |
262
267
  | --- | --- | --- | --- |
263
- | 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; Cursor / Codex / Antigravity `bkit-guardrails` hook. Codex ask → advisory |
264
- | Secret files | Read tool; shell reads on Cursor, Codex, Antigravity | Read tool: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*`. Shell reads of any of them: ask on Cursor and Antigravity, advisory on Codex, not gated on Claude and opencode (§ Permissions / auto-approve) | Codex shell → advisory |
265
- | Network | `curl` / `wget`, fetch tool | ask unless host ∈ allowlist (§ Network allowlist) | Advisory on Claude shell, Codex; Antigravity denies once, retry passes |
266
- | Shell-as-edit-channel | `sed -i`, redirect into a source file | Advisory: edit skips pre-edit gates | All hosts except opencode |
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
+ | 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 |
267
272
  | 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 |
268
273
  | ReadGuard | Repeat read of an unchanged range | Use-earlier-output note | Advisory, never blocks |
269
274
 
270
- - **Fail-open** everywhere: a hook that cannot read its payload allows. Cursor's `failClosed` on `bkit-guardrails.cjs` blocks only when the hook process itself crashes.
271
- - **Tool allowlists:** per-agent `tools:` gives reviewers read tools only; Codex ignores `tools:` (§ Codex CLI).
275
+ - **Fail-open** everywhere: a hook that cannot read its payload allows the call. Cursor's `failClosed` on `bkit-guardrails.cjs` blocks only when the hook process itself crashes.
276
+ - **Tool allowlists:** per-agent `tools:` gives reviewers read tools only. Codex ignores `tools:` (§ Codex CLI).
272
277
 
273
278
  ---
274
279
 
@@ -281,152 +286,244 @@ Per-action gates, all five hosts, subagents included. Overview only; per-host en
281
286
  | Script location | `.claude/hooks/*.sh` | `.cursor/hooks/*.sh` |
282
287
  | Trigger names | `SessionStart`, `Stop`, others | `sessionStart`, `stop` (camelCase, lowercase first letter) |
283
288
  | Stdin payload | `{ session_id, transcript_path, cwd, permission_mode }` | `{ session_id, is_background_agent, composer_mode }` (sessionStart); `{ status }` (stop) |
284
- | Blocking | **Cannot block** — non-zero exit treated as non-blocking. Must inject `additionalContext` HARD STOP into prompt + write reason to stderr. | **Can block** via `failClosed: true`. Non-zero exit aborts session. |
289
+ | Blocking | Cannot block: a non-zero exit is treated as non-blocking. Must inject an `additionalContext` HARD STOP into the prompt and write the reason to stderr. | Can block via `failClosed: true`. A non-zero exit aborts the session. |
285
290
  | Output format (sessionStart) | JSON: `{ "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "..." } }` | JSON: `{ "additional_context": "..." }` (snake_case) |
286
291
  | Stop hook config | `Stop` array | `stop[].loop_limit` (controls iteration cap; `null` = unlimited) |
287
292
  | Telemetry | Not part of host (custom in script) | Not part of host (custom in script — see `postflight.sh` log-drain pattern) |
288
293
 
289
- **Install behaviour:** hook scripts are **generated at install** (per host, not from `.agents/`). Semantic differences (blocking, stdin, output JSON) prevent one script for every host, so each host keeps a small hook source (`.bkit/core/.<host>/hooks/`, `.bkit/core/.opencode/plugin/`) holding only its module syntax, payload adapter and output shape. Code every host shares lives once in `.bkit/core/hooks/`; install splices it in wherever a template line reads `// {{BKIT_PART <file>}}` / `# {{BKIT_PART <file>}}` (`.bkit/core/engine/render/parts.ts`). The generated file is plain JS / bash with no runtime call into bkit, so it works without `node_modules`.
294
+ **Install behaviour:** hook scripts are generated at install (per host, not from `.agents/`). Semantic differences (blocking, stdin, output JSON) prevent one script for every host, so each host keeps a small hook source (`.bkit/core/.<host>/hooks/`, `.bkit/core/.opencode/plugin/`) holding only its module syntax, payload adapter and output shape. Code every host shares lives once in `.bkit/core/hooks/`; install splices it in wherever a template line reads `// {{BKIT_PART <file>}}` / `# {{BKIT_PART <file>}}` (`.bkit/core/engine/render/parts.ts`). The generated file is plain JS / bash with no runtime call into bkit, so it works without `node_modules`.
290
295
 
291
296
  <!-- prettier-ignore -->
292
297
  | Part | Shared by | Holds |
293
298
  | --- | --- | --- |
294
- | `gateguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
299
+ | `gateguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `gateguard` | gate-config table, checklists, docs advisory, dedup state, `firstTouchAdvice` |
295
300
  | `gateguard-edit-payload.js` | Claude, Cursor `gateguard` | `Edit` / `Write` / `MultiEdit` payload adapter `bkitGateguard(payload)` |
296
- | `readguard-engine.js` | Claude, Cursor, Codex, Google Antigravity, opencode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
297
- | `readguard-payload.js` | Claude, Cursor, Codex, Google Antigravity `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
298
- | `antigravity-hook.js` | Google Antigravity `gateguard`, `guardrails`, `readguard` | Antigravity envelope → Claude-family shape (`fromAntigravityPayload`), call signature, deny-once advisory delivery (`adviseOnce`) |
299
- | `guardrails-shell.js` | Claude, Cursor, Codex, Google Antigravity `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) |
300
- | `guardrails-tiers.js` | Cursor, Codex, Google Antigravity `guardrails` | git parsing (`parseGit`), deny + ask rules, `secretFileKind`, shell secret-read detection, `classifyShell` precedence |
301
- | `guardrails-read.js` | Cursor, Google Antigravity `guardrails` | `classifyRead` over `secretFileKind`: deny `*.pem` / `*.p12` / `id_rsa`, ask `.env` / `.env.*` (not `.env.example`) |
301
+ | `readguard-engine.js` | Claude, Codex, Antigravity, Cursor, OpenCode `readguard` | shell-read parser, line-range log per (session, agent), repeat-read note, `resetReadLog` |
302
+ | `readguard-payload.js` | Claude, Codex, Antigravity, Cursor `readguard` | read / shell payload adapter `bkitReadguard(payload)`; compaction event → reset |
303
+ | `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`) |
302
307
  | `preflight-linear.sh` | Claude, Cursor `preflight` | Linear key / issue checks, GraphQL query, `bkit:auto` + terminal-state guards |
308
+ | `preflight-rules.sh` | Claude, Cursor `preflight` | the rules-read advisory sentence and its `emit_context` call, merged into the one SessionStart JSON document |
309
+ | `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
+
311
+ Per host, outside the parts:
312
+
313
+ - Claude `gateguard` / `guardrails`: the `require` and `hookSpecificOutput` driver. Guardrails is advisory-only.
314
+ - Codex: the `apply_patch` envelope parser, with the ask tier emitted as advisory.
315
+ - 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
+ - Cursor: the `{ permission }` output, guardrails `Read|TabRead` path extraction, and gateguard workspace-relative path resolution.
317
+ - 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.
318
+ - `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
+
320
+ ### Rules-read advisory
321
+
322
+ 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).
323
+
324
+ <!-- prettier-ignore -->
325
+ | Host | File | Registration | Delivery |
326
+ | --- | --- | --- | --- |
327
+ | Claude | `.claude/hooks/bkit-preflight.sh` | `.claude/settings.json` → `hooks.SessionStart` | spliced from the part `preflight-rules.sh`, merged into the one session-start JSON document: the advisory alone on an IDE session, the advisory plus the Linear guard result on a cloud session, from a `printf` path that needs no `python3` |
328
+ | Codex | `.codex/hooks/bkit-rules.cjs` | `.codex/hooks.json` → `hooks.PreToolUse`, two single-value groups (`apply_patch`, `Bash`) | no session-start event: `additionalContext` once per session |
329
+ | Antigravity | `.agents/plugins/bkit/hooks/bkit-rules.cjs` | `.agents/plugins/bkit/hooks.json` → `hooks.PreToolUse` (`write_to_file\|replace_file_content\|view_file\|run_command`) | no session-start event: deny the first call once with the advisory as `reason`, allow the identical retry |
330
+ | Cursor | `.cursor/hooks/bkit-preflight.sh` | `.cursor/hooks.json` → `hooks.sessionStart` | same part, same one-document merge, in Cursor's `{ additional_context }` shape |
331
+ | OpenCode | `.opencode/plugin/bkit-rules.js` | `.opencode/opencode.json` → `plugin` array (spec `./plugin/bkit-rules.js`) | no session-start event: appended to the first tool result in `execute.after` |
332
+
333
+ **Codex registration:** two single-value `PreToolUse` groups (`apply_patch`, `Bash`), the shape every shipped Codex matcher uses. Alternation is unverified on that host, where a matcher that never fires still installs and exits 0 silently. Project-local hooks load only once the `.codex/` layer is trusted (§ host table above).
303
334
 
304
- Per host, outside the parts: Claude `gateguard` / `guardrails` — `require` + `hookSpecificOutput` driver, guardrails advisory-only; Cursor — `{ permission }` output, guardrails `Read|TabRead` path extraction, gateguard workspace-relative path resolve; Codex — `apply_patch` envelope parser, ask tier emitted as advisory; Google Antigravity — `antigravity-hook.js` envelope conversion + deny-once delivery, `{ decision, reason }` driver, `write_to_file` / `replace_file_content` edit tools (path `TargetFile`), `view_file` and `run_command` (`CommandLine`); opencode — ES module, `write` / `edit` / `patch` (`apply_patch`) vocabulary, every `*** Add|Update|Delete File:` / `*** Move to:` target of a `patchText` checked (deny mode blocks if any target is a first touch), checklist appended to the tool result in `execute.after` + throw from `execute.before` to block (2.0 exposes no pre-edit context hook, and stderr does not reach the model); `preflight` — trigger (Claude `LINEAR_ISSUE_ID`, Cursor `is_background_agent` + `.bkit/.runtime-cursor` marker), Claude-only Darwin brew check, `emit_context` shape.
335
+ **Dedup scope:** once per session. The two SessionStart hooks fire once per session and hold no state. The three first-tool-call hooks dedup by the host's session id (Codex `session_id`, Antigravity `conversationId`, OpenCode `sessionID`), with their state in the OS temp dir, GC'd after 24h. A payload with no session id falls back to one shared bucket. Codex reports the parent's `session_id` inside a subagent, and no agent id, so a subagent can miss an advisory its parent already consumed. § GateGuard records the same limit. On OpenCode a subagent runs in its own session and gets its own advisory.
336
+
337
+ **Ownership:** as in § GateGuard. bkit owns the advisory sentence and the once-per-session helper between the markers, and the consumer owns the driver below them.
305
338
 
306
339
  ### GateGuard
307
340
 
308
- Advisory hook, on all five hosts (Claude Code, Cursor, Codex, Google Antigravity, opencode). Claude / Cursor / Codex inject the checklist pre-edit (PreToolUse); Antigravity denies the first edit of a file once with the checklist as the reason (the only text its hooks deliver to the model) and allows the retry; opencode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook — the first edit's result, not a pre-edit gate — and reserves the pre-execute hook for deny mode. First file touch per session → investigation checklist; 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/` (reference copies; in bkit's own repo, package name `@cbartens/bkit`, that folder is the template source and stays guarded); new-file writes → reuse-over-duplicate nudge; `docs/**.md` (not `docs/plans/`) → density advisory appended. **fail-open**, **subagents included**, dedup `(session, agent, file)` via OS-temp state, 24h TTL.
341
+ An advisory hook, on all five hosts (Claude, Codex, Antigravity, Cursor, OpenCode). Each host delivers the checklist its own way:
342
+
343
+ - Claude / Codex / Cursor inject the checklist before the edit (PreToolUse).
344
+ - Antigravity denies the first edit of a file once, with the checklist as the reason (the only text its hooks deliver to the model), and allows the retry.
345
+ - OpenCode 2.0 exposes no pre-edit context hook, so it appends the checklist to the tool result in the post-execute hook. The checklist arrives with the first edit's result, not as a pre-edit gate. The pre-execute hook is reserved for deny mode.
346
+
347
+ What it advises:
348
+
349
+ - First file touch per session → investigation checklist.
350
+ - 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
+ - New-file writes → reuse-over-duplicate nudge.
352
+ - `docs/**.md` (not `docs/plans/`) → density advisory appended.
353
+
354
+ It is fail-open and includes subagents. It dedups on `(session, agent, file)` via OS-temp state, with a 24h TTL.
309
355
 
310
356
  <!-- prettier-ignore -->
311
357
  | Host | Implementation | File | Registration |
312
358
  | --- | --- | --- | --- |
313
- | Claude Code | `bkit-gateguard.cjs` (CJS) | `.claude/hooks/bkit-gateguard.cjs` | `.claude/settings.json` → `hooks.PreToolUse` on `Edit\|Write\|MultiEdit` |
314
- | 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/`) |
315
- | 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` — an advisory hook that fails closed would block the edit it only meant to comment on |
316
- | 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` |
359
+ | Claude | `bkit-gateguard.cjs` (CJS) | `.claude/hooks/bkit-gateguard.cjs` | `.claude/settings.json` → `hooks.PreToolUse` on `Edit\|Write\|MultiEdit` |
360
+ | 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` |
317
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` |
318
- | 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` |
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` |
364
+ | 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
+
366
+ **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:
367
+
368
+ - **If** the hash matches a bkit release → the file is replaced wholesale.
369
+ - **If** the hash is unknown → the block is appended, and wiring instructions are printed.
370
+
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.
372
+
373
+ **Modes (env):**
374
+
375
+ - Unset → advisory [default].
376
+ - `BKIT_GATEGUARD=off` → disabled.
377
+ - `BKIT_GATEGUARD=deny` → deny the first touch (checklist as the reason), and allow the retry.
378
+ - `BKIT_ALLOW_CONFIG_EDIT=1` suppresses the gate-config advisory.
319
379
 
320
- **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 + 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 Code parses hook stdout as one JSON document, so two emitters would produce `{...}{...}` and the whole hook's output — bkit's included — is discarded. Marker-less file on upgrade → hash matches a bkit release: replaced wholesale; hash unknown: block appended plus printed wiring instructions. Uninstall strips the block, leaving 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()`.
380
+ **Subagents:** not exempt on any host. Dedup is per (session, agent, file) wherever the host names the agent.
321
381
 
322
- **Modes (env):** unset → advisory _[default]_; `BKIT_GATEGUARD=off` → disabled; `BKIT_GATEGUARD=deny` → deny first touch (checklist as reason), allow retry. `BKIT_ALLOW_CONFIG_EDIT=1` suppresses gate-config advisory.
382
+ - Claude: a subagent shares its parent's `session_id`. Its `agent_id` keys its own dedup, so it gets its own checklist.
383
+ - Codex: tool payloads carry the parent's `session_id` inside a subagent, and no agent id.
384
+ - Antigravity: no native subagents (prompts run in-session; `agy` runs are their own conversation).
385
+ - Cursor: no subagent marker.
386
+ - OpenCode: a subagent runs in its own session.
323
387
 
324
- **Subagents:** not exempt on any host; dedup is per (session, agent, file) wherever the host names the agent. Claude Code — a subagent shares its parent's `session_id`; its `agent_id` keys its own dedup, so it gets its own checklist. opencode — a subagent runs in its own session. Codex — tool payloads carry the parent's `session_id` inside a subagent and no agent id; Cursor — no subagent marker; Antigravity — no native subagents (prompts run in-session; `agy` runs are their own conversation). On Codex and Cursor a subagent editing a file its parent already touched gets no checklist.
388
+ On Codex and Cursor a subagent editing a file its parent already touched gets no checklist.
325
389
 
326
- **Deny mode, per host:** Claude and Codex `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`; Antigravity `decision: "deny"` with the checklist as `reason` — the same as its advisory mode; Cursor `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model); opencode throws from `execute.before` — the only hook that can block — and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model. Same behaviour, three delivery mechanisms across five hosts; asserted uniformly in `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts`.
390
+ **Deny mode, per host:**
327
391
 
328
- **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 differs only where the runtime forces it — ES module rather than CJS, tool vocabulary `write`/`edit`/`patch` rather than `Edit`/`Write`/`MultiEdit`, plus a `patchText` envelope parser for `patch`. Codex's 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.
392
+ - Claude and Codex: `permissionDecision: "deny"` with the checklist as `permissionDecisionReason`.
393
+ - Antigravity: `decision: "deny"` with the checklist as `reason`, the same as its advisory mode.
394
+ - Cursor: `permission: "deny"` with the checklist as `agent_message` (`user_message` goes to the human, not the model).
395
+ - OpenCode: throws from `execute.before`, the only hook that can block, and appends the checklist to the tool result in `execute.after`, because 2.0 exposes no pre-edit context hook and stderr does not reach the model.
396
+
397
+ The behaviour is the same, with four delivery mechanisms across five hosts. `.bkit/core/engine/audits/hooks/gateguard-parity.integration.test.ts` asserts it uniformly.
398
+
399
+ **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.
329
400
 
330
401
  ### ReadGuard
331
402
 
332
- Advisory repeat-read hook, on all five hosts. A read of a line range the same agent already read in this conversation, file unchanged since (same mtime + size), gets a note: use the earlier output; re-read only if it left context (summarised, or read by another agent). Tracks read-tool calls (`offset` / `limit`, `StartLine` / `EndLine`; no limit → first 2000 lines, opencode → whole file) and plain shell reads — `cat FILE`, `sed -n 'A,Bp' FILE`, `head` / `tail` with a line count; pipes, lists, redirects, substitutions, globs and other programs are not tracked. Ranges merge per file; a changed file starts a fresh log. **fail-open**, never blocks, log in OS temp (`bkit-readguard/`), 24h TTL. `BKIT_READGUARD=off` → disabled.
403
+ 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).
404
+
405
+ - It tracks read-tool calls (`offset` / `limit`, `StartLine` / `EndLine`; no limit → first 2000 lines, OpenCode → whole file).
406
+ - It tracks plain shell reads: `cat FILE`, `sed -n 'A,Bp' FILE`, and `head` / `tail` with a line count. Pipes, lists, redirects, substitutions, globs and other programs are not tracked.
407
+ - Ranges merge per file. A changed file starts a fresh log.
408
+
409
+ It is fail-open and never blocks. The log lives in per-user OS temp (`bkit-readguard-<uid>/`; kept in memory when that cannot be written), with a 24h TTL. `BKIT_READGUARD=off` → disabled.
333
410
 
334
411
  <!-- prettier-ignore -->
335
412
  | Host | File | Registration | Delivery | Log key | Reset on summary |
336
413
  | --- | --- | --- | --- | --- | --- |
337
- | Claude Code | `.claude/hooks/bkit-readguard.cjs` | `.claude/settings.json` → `PreToolUse` (`Read\|Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` + `agent_id` | `PreCompact` |
338
- | Cursor | `.cursor/hooks/bkit-readguard.cjs` | `.cursor/hooks.json` → `preToolUse` (`Read\|Shell`) + `preCompact`, no `failClosed` | `additional_context` on an allow, before the read | `conversation_id` | `preCompact` |
414
+ | Claude | `.claude/hooks/bkit-readguard.cjs` | `.claude/settings.json` → `PreToolUse` (`Read\|Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` + `agent_id` | `PreCompact` |
339
415
  | Codex | `.codex/hooks/bkit-readguard.cjs` | `.codex/hooks.json` → `PreToolUse` (`Bash`) + `PreCompact` | `additionalContext`, before the read | `session_id` | `PreCompact` |
340
416
  | Antigravity | `.agents/plugins/bkit/hooks/bkit-readguard.cjs` | `.agents/plugins/bkit/hooks.json` → `PreToolUse` (`view_file\|run_command`) | deny once with the note as `reason`, before the read; the identical retry passes | `conversationId` | none — no compaction hook |
341
- | opencode | `.opencode/plugin/bkit-readguard.js` | `.opencode/opencode.json` → `plugin` array | appended to the tool result in `execute.after`, after the read | `sessionID` | 1.x `session.compacted` event; 2.0 none — no event subscription for plugins |
417
+ | Cursor | `.cursor/hooks/bkit-readguard.cjs` | `.cursor/hooks.json` → `preToolUse` (`Read\|Shell`) + `preCompact`, no `failClosed` | `additional_context` on an allow, before the read | `conversation_id` | `preCompact` |
418
+ | OpenCode | `.opencode/plugin/bkit-readguard.js` | `.opencode/opencode.json` → `plugin` array | appended to the tool result in `execute.after`, after the read | `sessionID` | 1.x `session.compacted` event; 2.0 none — no event subscription for plugins |
419
+
420
+ **Gaps:**
421
+
422
+ - Codex has no read tool, so it tracks shell reads only.
423
+ - Codex, Antigravity and Cursor tool payloads carry no subagent id, and Codex subagents share the parent `session_id`, so a subagent can be told about its parent's read. The note's re-read clause covers it.
424
+ - Antigravity and OpenCode 2.0 never reset on a summary. The same clause covers it.
425
+ - OpenCode's note arrives with the repeated read, not before it. Antigravity's note costs one extra call (the retry).
342
426
 
343
- **Gaps:** Codex has no read tool, so shell reads only. Codex, Cursor and Antigravity tool payloads carry no subagent id, and Codex subagents share the parent `session_id`, so a subagent can be told about its parent's read — the note's re-read clause covers it. Antigravity and opencode 2.0 never reset on a summary — same clause. opencode's note arrives with the repeated read, not before it; Antigravity's costs one extra call (the retry). Shared code: `readguard-engine.js` everywhere, `readguard-payload.js` on the four CJS hosts plus `antigravity-hook.js` on Antigravity; the Claude, Cursor and Codex managed blocks are byte-identical (test-asserted in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`). Ownership as § GateGuard.
427
+ **Shared code:** `readguard-engine.js` everywhere, and `readguard-payload.js` on the four CJS hosts plus `antigravity-hook.js` on Antigravity. The Claude, Codex and Cursor managed blocks are byte-identical (test-asserted in `.bkit/core/engine/audits/hooks/readguard-parity.integration.test.ts`). Ownership is as in § GateGuard.
344
428
 
345
429
  ---
346
430
 
347
431
  ## Permissions / auto-approve
348
432
 
349
433
  <!-- prettier-ignore -->
350
- | Concern | Claude | Cursor | opencode | Codex | Antigravity |
434
+ | Concern | Claude | Codex | Antigravity | Cursor | OpenCode |
351
435
  | --- | --- | --- | --- | --- | --- |
352
- | 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` | `.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 | **none** — no file-read tool. Deferral `codex-read-tier-gates-not-wired-file-read-tool-name-unverified` | `.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 |
353
- | 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 | `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 | same detection as Cursor via `PreToolUse` (`Bash`) — advisory `additionalContext`, command runs | same detection as Cursor via `PreToolUse` (`run_command`) — Antigravity's own `ask` |
354
- | 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 | `.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 | `.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` |
355
- | 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` ask unless host ∈ `.bkit/allowlist.json` (tooling ∪ 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`) | `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 |
356
- | Granularity | Per-tool glob | Hook script (project-scoped, fail-open; `failClosed` blocks only a crashed hook) | Per-path / per-command glob in `permission` | Hook script (project-scoped, fail-open; fires only once `.codex/` is trusted) | Hook script (workspace plugin, fail-open) |
357
- | Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` | Implicit per-mode (Composer / Agent / Background) | `opencode --auto` + permission defaults | host defaults — bkit writes no `.codex/config.toml` | host defaults — bkit ships none |
358
- | MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` | none written | none written |
359
- | MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` | none — no project-level MCP approval file | none written |
360
- | Local-only (not shipped) | `.claude/settings.local.json` (`additionalDirectories`, extra allows) | Cursor project/user settings / MCP as needed | `~/.config/opencode/opencode.json` → `permission.external_directory` | `~/.codex/config.toml` | user-level settings |
361
-
362
- **Install behaviour:** template drops, host-specific encoding of the **same** shared policy. No single canonical JSON — each host's native form kept in lockstep; asserted in `.bkit/core/engine/install/modules/index.integration.test.ts` § permissions-parity. Machine-local paths stay out of templates.
436
+ | 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` |
441
+ | 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
+ | 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
+ | 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
+ | 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
+
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.
363
447
 
364
448
  ### Network allowlist — one source, five hosts
365
449
 
366
- **Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` **after** `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
450
+ **Source of truth:** bkit's own hosts come from the egress registry (`.bkit/core/engine/shared/egress.ts`) and must never be re-declared. Stack domains come from consumer `.agents/context.md` → `<!-- allowed-domains:start -->` after `<!-- bkit:end -->` (apex domains). Never ship Vercel/Supabase/Sentry/etc. into every consumer.
367
451
 
368
- **`bkit install` / `bkit upgrade` apply that set differently per host** — same policy, native mechanics:
452
+ `bkit install` / `bkit upgrade` apply that set differently per host: the same policy, with each host's native mechanics.
369
453
 
370
454
  <!-- prettier-ignore -->
371
455
  | Host | Where the allowlist lives | Why that shape |
372
456
  | --- | --- | --- |
373
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(*)`. |
374
- | **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. |
375
- | **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. |
376
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. |
377
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. |
460
+ | **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. |
378
462
 
379
- **`.bkit/allowlist.json`** — core-owned, written on every install / upgrade whatever the host set, removed by full uninstall. **Do not hand-edit** — 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 — Antigravity runs plugin hooks from the plugin dir. Missing file => every host reads as unknown; the hook embeds no list, because a second copy drifts from the registry silently.
463
+ **`.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.
380
464
 
381
- **Cloud egress (separate):** the derived registry union the same `allowed-domains` feed `.claude/bkit-cloud.md` / `.cursor/bkit-cloud.md` paste instructions for dashboard network Custom allowlists — that is proxy egress, not local agent permission files. See `.agents/context.md` § Allowed domains and `.bkit/cloud.md`.
465
+ **Cloud egress (separate):** the derived registry, unioned with the same `allowed-domains`, feeds the paste instructions in `.claude/bkit-cloud.md` / `.codex/bkit-cloud.md` / `.cursor/bkit-cloud.md` for dashboard network Custom allowlists. That is proxy egress, not local agent permission files. See `.agents/context.md` § Allowed domains and `.bkit/cloud.md`.
382
466
 
383
467
  ### MCP servers — one source, three encodings
384
468
 
385
- **Source of truth:** consumer `.agents/context.md` → `<!-- mcp-servers:start -->` **after** `<!-- bkit:end -->`, one server name per line. Every tool on a listed server (reads and writes) runs without a prompt on every host; an unlisted server keeps each host's default. bkit ships no server names — only what the consumer lists.
469
+ **Source of truth:** consumer `.agents/context.md` → `<!-- mcp-servers:start -->` after `<!-- bkit:end -->`, one server name per line. Every tool on a listed server (reads and writes) runs without a prompt on every host. An unlisted server keeps each host's default. bkit ships no server names, only what the consumer lists.
386
470
 
387
471
  <!-- prettier-ignore -->
388
472
  | Host | Where the allows live | Rule per server `<s>` |
389
473
  | --- | --- | --- |
390
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) |
391
475
  | **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>:*)` |
392
- | **OpenCode** | Baked into `.opencode/opencode.json` → `permission` | `"<s>_*": "allow"` — opencode names MCP tools `<s>_<tool>` |
476
+ | **OpenCode** | Baked into `.opencode/opencode.json` → `permission` | `"<s>_*": "allow"` — OpenCode names MCP tools `<s>_<tool>` |
393
477
 
394
- **Spelling is per host:** a name matches a tool id verbatim — list each spelling a host uses (`sentry` for a `.mcp.json` server, `Sentry` for the claude.ai connector). **Do not hand-edit** `.cursor/cli.json` — it is regenerated whole on install/upgrade. Codex: no project-level MCP approval file — out of scope.
478
+ **Spelling is per host:** a name matches a tool id verbatim, so list each spelling a host uses (`sentry` for a `.mcp.json` server, `Sentry` for the claude.ai connector). Do not hand-edit `.cursor/cli.json`, because it is regenerated whole on install/upgrade. Codex has no project-level MCP approval file, so it is out of scope.
395
479
 
396
480
  ### MCP config asymmetry — GitHub tracker
397
481
 
398
- Both hosts: same `mcpServers` shape; files differ:
482
+ Both hosts use the same `mcpServers` shape, in different files:
399
483
 
400
484
  <!-- prettier-ignore -->
401
485
  | Host | File | Written by |
402
486
  | --- | --- | --- |
403
- | Claude Code | `.mcp.json` at repo root | `bkit install --tracker=github` writes the `github` entry |
487
+ | Claude | `.mcp.json` at repo root | `bkit install --tracker=github` writes the `github` entry |
404
488
  | Cursor | `.cursor/mcp.json` | `bkit install --tracker=github` writes the same `mcpServers.github` block |
405
489
 
406
- Both: `"type": "http"`, `"url": "https://api.githubcopilot.com/mcp/"`, `"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}", "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions" }`. `${BKIT_GH_TOKEN}` at session start — must be in shell (local) or dashboard env (cloud). See `.bkit/cloud.md` § MCP issue-tracker integration for full JSON.
490
+ Both: `"type": "http"`, `"url": "https://api.githubcopilot.com/mcp/"`, `"headers": { "Authorization": "Bearer ${BKIT_GH_TOKEN}", "X-MCP-Toolsets": "context,issues,pull_requests,repos,users,projects,actions" }`. `${BKIT_GH_TOKEN}` is read at session start, so it must be in the shell (local) or the dashboard env (cloud). See `.bkit/cloud.md` § MCP issue-tracker integration for the full JSON.
491
+
492
+ **bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`.
493
+
494
+ - **If** the file is absent → it gets the tracker-filtered render.
495
+ - **If** the file exists → install and upgrade reset the keys the template sets in that entry, and keep every other key, in its order. Malformed JSON stops the install.
407
496
 
408
- **bkit owns one entry per file.** In `.mcp.json` / `.cursor/mcp.json` bkit owns only `mcpServers.<tracker>`: an absent file gets the tracker-filtered render; in an existing file install and upgrade reset the keys the template sets in that entry and keep every other key, in its order (malformed JSON stops the install). Inside the entry, extra keys and headers stay the consumer's, and `X-MCP-Toolsets` keeps the consumer's list and gains any template toolset it lacks, so a repo can enable more toolsets without drift. The same rule covers `mcp.<tracker>` in `.opencode/opencode.json`. `bkit check` reports a pending reset. Tracker `none` owns no entry. A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and removes the old tracker's `linear` entry from all three files while it still equals the template; an entry the consumer edited stays, named in a warning (and in `mcp-extra-server-linear`). `github` stays on every switch. Uninstall removes bkit's entry while it still equals the template. Advisories: `mcp-missing-server-<name>` (file lacks the configured tracker's server; `none` needs none), `mcp-extra-server-<name>` (`linear` entry while the configured tracker is not `linear`; also checked in `.opencode/opencode.json` `mcp`). `github` never flagged as extra: every phase workflow's gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls it — under `linear` / `none`, add it by hand to keep that fallback. Consumer-added MCP servers never flagged.
497
+ Inside the entry, extra keys and headers stay the consumer's. `X-MCP-Toolsets` keeps the consumer's list and gains any template toolset it lacks, so a repo can enable more toolsets without drift. The same rule covers `mcp.<tracker>` in `.opencode/opencode.json`. `bkit check` reports a pending reset. Tracker `none` owns no entry.
409
498
 
410
- > Note: `mcpServers` in `.claude/settings.json` silently ignored for server defs — only `.mcp.json` (project) or `claude mcp add` (user) take effect. Tool-permission `allow` (`mcp__github__*`) remain in settings.
499
+ A tracker switch (e.g. `--tracker=linear` → `--tracker=github`) adds the new entry and removes the old tracker's `linear` entry from all three files while it still equals the template. An entry the consumer edited stays, and is named in a warning (and in `mcp-extra-server-linear`). `github` stays on every switch. Uninstall removes bkit's entry while it still equals the template.
500
+
501
+ Advisories:
502
+
503
+ - `mcp-missing-server-<name>`: the file lacks the configured tracker's server. `none` needs none.
504
+ - `mcp-extra-server-<name>`: a `linear` entry while the configured tracker is not `linear`. Also checked in `.opencode/opencode.json` `mcp`.
505
+
506
+ `github` is never flagged as extra, because every phase workflow's gh MCP fallback (PR / CI / merge when `gh` is unavailable) calls it. Under `linear` / `none`, add it by hand to keep that fallback. Consumer-added MCP servers are never flagged.
507
+
508
+ > Note: `mcpServers` in `.claude/settings.json` is silently ignored for server defs. Only `.mcp.json` (project) or `claude mcp add` (user) take effect. Tool-permission `allow` rules (`mcp__github__*`) remain in settings.
411
509
 
412
510
  ---
413
511
 
414
512
  ## Context compaction
415
513
 
416
- bkit ships `autoCompactWindow: 300000` in the frontmatter of every `bkit-*` Claude Code subagent: the agent summarises at 300,000 tokens at the latest. Safety net, not the cap (group size, the 160k handover and `maxTurns` stop an agent first). It only lowers the window: a lower repo / user setting or `CLAUDE_CODE_AUTO_COMPACT_WINDOW` still wins. Needs Claude Code v2.1.296+; plain integer only (`300k` reads as 300, out of range, ignored). Main sessions on every host stay consumer settings (tips below); each host auto-summarises near the model's full window by default. Effective threshold = min(setting, model window). Per-host facts and sources: [compaction options by host](https://github.com/cbartens/bkit/issues/690).
417
-
514
+ bkit ships `autoCompactWindow: 300000` in the frontmatter of every `bkit-*` Claude subagent: the agent summarises at 300,000 tokens at the latest. It is a safety net, not the cap (group size, the 160k handover and `maxTurns` stop an agent first). It only lowers the window: a lower repo / user setting or `CLAUDE_CODE_AUTO_COMPACT_WINDOW` still wins. It needs Claude v2.1.296+, and takes a plain integer only (`300k` reads as 300, which is out of range and ignored). Main sessions on every host stay consumer settings (tips below). Each host auto-summarises near the model's full window by default. Effective threshold = min(setting, model window).
418
515
  <!-- prettier-ignore -->
419
516
  | Host | Per agent (bkit ships) | Project-wide setting (tip) | Notes |
420
517
  | --- | --- | --- | --- |
421
- | Claude Code | `autoCompactWindow: 300000` frontmatter on every `bkit-*` agent (integer 100,000-1,000,000; source: code.claude.com/docs/en/sub-agents.md § Set the auto-compact window for one subagent) | `.claude/settings.json` → `"autoCompactWindow": 300000` (or `"auto"`) — install / upgrade keep keys bkit does not own; also changes the main session | per person: `.claude/settings.local.json`; env `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats every settings file and agent frontmatter |
422
- | Codex CLI | none — a role file parses `model_auto_compact_token_limit` but Codex discards it when applying the role (openai/codex `core/src/agent/role.rs:37-48`); subagents copy the parent's value (`core/src/agent/child_config.rs:132-141`) | `.codex/config.toml` → `model_auto_compact_token_limit = 300000`, above the first `[table]` header (below one, the key belongs to that table and does nothing); also changes the main session | read only once the project is trusted; one run: `codex -c model_auto_compact_token_limit=N`; above 90% of the model window, Codex uses 90% |
423
- | opencode | none — no agent field (sst/opencode `packages/schema/src/config/agent.ts`) | none — no absolute-count trigger. Auto-compaction fires at the model's input (else context) limit minus `compaction.buffer` (default 15%, at least 16,000 tokens); a buffer larger than the window is ignored | per model: `providers.<id>.models.<alias>` = `{modelID: "<real>", limit: {input: N}}` with the agent pinned to `<id>/<alias>`, `N` ~ target + buffer (~353,000 for 300k); one entry per model per provider, catalog models only, untested end to end. Not `compaction.buffer`: one global buffer large enough for a 1M model compacts too early on 128k-200k models |
518
+ | Claude | `autoCompactWindow: 300000` frontmatter on every `bkit-*` agent (integer 100,000-1,000,000; source: code.claude.com/docs/en/sub-agents.md § Set the auto-compact window for one subagent) | `.claude/settings.json` → `"autoCompactWindow": 300000` (or `"auto"`) — install / upgrade keep keys bkit does not own; also changes the main session | per person: `.claude/settings.local.json`; env `CLAUDE_CODE_AUTO_COMPACT_WINDOW` beats every settings file and agent frontmatter |
519
+ | Codex | none — a role file parses `model_auto_compact_token_limit` but Codex discards it when applying the role (openai/codex `core/src/agent/role.rs:37-48`); subagents copy the parent's value (`core/src/agent/child_config.rs:132-141`) | `.codex/config.toml` → `model_auto_compact_token_limit = 300000`, above the first `[table]` header (below one, the key belongs to that table and does nothing); also changes the main session | read only once the project is trusted; one run: `codex -c model_auto_compact_token_limit=N`; above 90% of the model window, Codex uses 90% |
520
+ | Antigravity | none — bkit agents run in the main session (`view_file`), no separate agent context | none — threshold internal (~135k), no setting / env reaches it (ai.google.dev/gemini-api/docs/antigravity-agent) | manual `/compact` |
424
521
  | Cursor | none — no compaction setting (cursor.com/docs/subagents.md § Model parameters) | none — trigger fixed server-side | `model: <id>[context=N]` shrinks the agent's whole window, not only where it summarises; valid values per model undocumented. Manual `/summarize` |
425
- | Google Antigravity | none — bkit agents run in the main session (`view_file`), no separate agent context | none — threshold internal (~135k), no setting / env reaches it (ai.google.dev/gemini-api/docs/antigravity-agent) | manual `/compact` |
522
+ | OpenCode | none — no agent field (sst/opencode `packages/schema/src/config/agent.ts`) | none — no absolute-count trigger. Auto-compaction fires at the model's input (else context) limit minus `compaction.buffer` (default 15%, at least 16,000 tokens); a buffer larger than the window is ignored | per model: `providers.<id>.models.<alias>` = `{modelID: "<real>", limit: {input: N}}` with the agent pinned to `<id>/<alias>`, `N` ~ target + buffer (~353,000 for 300k); one entry per model per provider, catalog models only, untested end to end. Not `compaction.buffer`: one global buffer large enough for a 1M model compacts too early on 128k-200k models |
426
523
 
427
- **Floor:** keep the window well above the largest single tool result plus the recent turns kept after a summary. Claude Code ends an agent whose context refills to the limit within 3 turns of a summary, 3 times in a row (`Autocompact is thrashing`).
524
+ **Floor:** keep the window well above the largest single tool result plus the recent turns kept after a summary. Claude ends an agent whose context refills to the limit within 3 turns of a summary, 3 times in a row (`Autocompact is thrashing`).
428
525
 
429
- **Compression proxies:** bkit ships none (caveman, Headroom). On 456 real Claude Code transcripts they saved ~1-3% of token cost: both keep the prompt cache intact, so each tool result is compressed once on arrival and reused, and tool results >= 2 KB are 27% of cost. Headroom's Kompress text model rewrote code (`=> void` → `void`). Method, results, scripts to measure own sessions: [comparison](https://github.com/cbartens/bkit/blob/main/tests/compression/bkit-caveman-headroom-compression-proxy-comparison.md). bkit cuts reading instead, losslessly: § ReadGuard + `Code reads` / `Narrow text search first` in `.agents/rules.md`.
526
+ **Compression proxies:** bkit ships none (caveman, Headroom). On 456 real Claude transcripts they saved ~1-3% of token cost. Both keep the prompt cache intact, so each tool result is compressed once on arrival and reused, and tool results >= 2 KB are 27% of cost. Headroom's Kompress text model rewrote code (`=> void` → `void`). The method, the results and scripts to measure your own sessions are in the [comparison](https://github.com/cbartens/bkit/blob/main/tests/experiments/compression/reports/bkit-caveman-headroom-compression-proxy-comparison.md). bkit cuts reading instead, losslessly: § ReadGuard, plus `Code reads` / `Narrow text search first` in `.agents/rules.md`.
430
527
 
431
528
  ## MCP project scope
432
529
 
@@ -443,46 +540,46 @@ Only servers in the repo's own files lock this way; claude.ai connectors cannot
443
540
 
444
541
  ## claude.ai connectors
445
542
 
446
- Claude Code loads every connector on the person's claude.ai account in every repo, and re-sends their tool names on every request whether used or not. `"disableClaudeAiConnectors": true` in `.claude/settings.json` stops that for the repo.
543
+ Claude loads every connector on the person's claude.ai account in every repo, and re-sends their tool names on every request whether used or not. `"disableClaudeAiConnectors": true` in `.claude/settings.json` stops that for the repo.
447
544
 
448
545
  <!-- prettier-ignore -->
449
546
  | Aspect | Detail |
450
547
  | --- | --- |
451
- | Stops | claude.ai connectors in Claude Code sessions for this repo — terminal and desktop app |
548
+ | Stops | claude.ai connectors in Claude sessions for this repo — terminal and desktop app |
452
549
  | Keeps | the repo's `.mcp.json` servers (bkit's tracker server included), `claude mcp add` servers, and the connectors themselves in claude.ai / desktop-app chats and cloud routines |
453
550
  | Before | move anything agents reach through a connector onto `.mcp.json` (§ MCP project scope), a context-fetch block or the provider CLI |
454
551
  | Per person | `false` in `.claude/settings.local.json` turns connectors back on |
455
552
  | Verify | `/context` before and after |
456
553
 
457
- bkit ships no default: the setting also hides each person's own connectors (mail, drive, …), and install / upgrade keep keys bkit does not own, so a shipped `true` could not be turned off in `.claude/settings.json`. The `claude-connectors` setup tip fires on a Claude Code repo that sets neither value.
554
+ bkit ships no default: the setting also hides each person's own connectors (mail, drive, …), and install / upgrade keep keys bkit does not own, so a shipped `true` could not be turned off in `.claude/settings.json`. The `claude-connectors` setup tip fires on a Claude repo that sets neither value.
458
555
 
459
556
  ---
460
557
 
461
558
  ## Runtime environment (cloud agents)
462
559
 
463
- > Setup recipe + alignment: `.bkit/cloud.md`. This section = host-diff matrix only.
560
+ > The setup recipe and alignment are in `.bkit/cloud.md`. This section holds the host-diff matrix only.
464
561
 
465
562
  <!-- prettier-ignore -->
466
- | Concern | Claude Code on the web | Cursor Background Agents |
467
- | --- | --- | --- |
468
- | Where env config lives | Claude app (per-environment), not in repo | In repo (`.cursor/`) |
469
- | Custom base image | Not supported — setup script layers on top of Anthropic-managed Ubuntu 24.04 | Supported — `.cursor/Dockerfile` |
470
- | Cold-start cache | Snapshot keyed by setup-script body hash (~7d TTL) | Docker image layers |
471
- | Per-snapshot install | `.claude/hooks/bkit-cloud-bootstrap.sh` (SessionStart, fires when `CLAUDE_CODE_REMOTE=true`) | `.cursor/environment.json` → `install` |
472
- | Build env | Setup script (paste-in via Claude app UI) | `.cursor/Dockerfile` (Cursor Cloud builds custom image) |
473
- | Install/start | n/a (handled by bootstrap hook) | `.cursor/environment.json` → `install`, `start`, `terminals[]`, `env`, `ports` |
474
- | Port forwarding | n/a | `.cursor/environment.json` → `terminals[].ports` |
475
- | Cloud-session detection | `CLAUDE_CODE_REMOTE=true` (env var) | `is_background_agent === true` (stdin JSON) |
476
- | Default network | `Trusted` allowlist (npm, GitHub, PyPI, Docker Hub, vale tarball) | Outbound open in the sandbox |
477
- | Reusable across repos | Setup script yes (generic snapshot); environment no — one per repo (secrets / PAT scope are per-repo) | No — Dockerfile per repo (copied from the bkit template and owned by the repo) |
478
- | Secrets | Env vars in Claude app (plaintext; rotate PATs) | Cursor Cloud env vars (Settings → Background Agents → Environment Variables) |
479
- | Linear preflight | `.claude/hooks/bkit-preflight.sh` (SessionStart, non-blocking — uses `additionalContext` HARD STOP) | `.cursor/hooks/bkit-preflight.sh` (`sessionStart`, `failClosed: true`, blocks on non-zero) |
480
-
481
- **Install behaviour:** template drops; project tokens at install. Both clouds aligned via bkit: vale 3.9.1, pnpm (corepack-pinned `package.json#packageManager`), gh CLI. See `.bkit/cloud.md` for paste-in recipe + sharing pattern.
563
+ | Concern | Claude on the web | Codex Cloud | Cursor Background Agents |
564
+ | --- | --- | --- | --- |
565
+ | Where env config lives | Claude app (per-environment), not in repo | ChatGPT **Settings > Codex Cloud > Environments** (per-environment), not in repo | In repo (`.cursor/`) |
566
+ | Custom base image | Not supported — setup script layers on top of Anthropic-managed Ubuntu 24.04 | Not used — install script layers on Codex's image | Supported — `.cursor/Dockerfile` |
567
+ | Cold-start cache | Snapshot keyed by setup-script body hash (~7d TTL) | Not documented | Docker image layers |
568
+ | Per-snapshot install | `.claude/hooks/bkit-cloud-bootstrap.sh` (SessionStart, fires when `CLAUDE_CODE_REMOTE=true`) | Install script tail (`pnpm install`, `vale sync`, `gh auth login`) | `.cursor/environment.json` → `install` |
569
+ | Build env | Setup script (paste-in via Claude app UI) | **Install script** (paste-in from `.codex/bkit-cloud.md`) | `.cursor/Dockerfile` (Cursor Cloud builds custom image) |
570
+ | Install / start | n/a (handled by bootstrap hook) | Install script | `.cursor/environment.json` → `install`, `start`, `terminals[]`, `env`, `ports` |
571
+ | Port forwarding | n/a | n/a | `.cursor/environment.json` → `terminals[].ports` |
572
+ | Cloud-session detection | `CLAUDE_CODE_REMOTE=true` (env var) | None — bkit ships no Codex cloud hook | `is_background_agent === true` (stdin JSON) |
573
+ | 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
+ | 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
+ | 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) |
577
+
578
+ **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.
482
579
 
483
580
  ---
484
581
 
485
- ## Models
582
+ ## Provider models
486
583
 
487
584
  ### Per-provider live model lookup
488
585
 
@@ -492,145 +589,205 @@ Installed provider catalog changes. Look up model IDs before pinning in `.openco
492
589
  | Provider | Command | Notes |
493
590
  | --- | --- | --- |
494
591
  | Claude (Anthropic) | `curl https://api.anthropic.com/v1/models -H "x-api-key: $BKIT_ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01"` | Canonical `Claude` column source. No key in-shell → cross-check via the OpenRouter `anthropic/*` mirror. |
495
- | Cursor | `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"` | `Cursor` column source. Catalog churns. Probed 2026-10-06: `cursor-grok-4.5-high`, `composer-2.5`, `claude-opus-5-thinking-high`, `claude-sonnet-5-thinking-high`/`-xhigh`, `gpt-5.6-*`, Fable 5. No Grok 4.7. No Opus 5.5 / Sonnet 5.5. |
496
- | OpenRouter | `curl https://openrouter.ai/api/v1/models` | **Public — no key.** Aggregator; `vendor/model` slugs (`:free` variants exist). Filter for tool-calling + coding models before pinning. |
592
+ | Cursor | `curl https://api.cursor.com/v0/models -u "$BKIT_CURSOR_API_KEY:"` | `Cursor` column source. Catalog churns. Probed 2026-10-28: `composer-2.5`, `cursor-grok-4.5-high` (+`-fast`), `claude-opus-5-thinking-high` (+`-fast`), `claude-fable-5-thinking-high`/`-xhigh`, `claude-sonnet-5-thinking-high`/`-xhigh`, `gpt-5.6-sol-high`/`-xhigh` (+`-fast`), `gpt-5.6-luna-high`, `gemini-3.7-flash-high`. Still no Grok 4.6 or 4.7, and no Opus 5.5 / Sonnet 5.5. Cursor's first-party pins are therefore unmeasured on 2.0 and stay as inherited. |
593
+ | OpenRouter | `curl https://openrouter.ai/api/v1/models` | Public, no key. Aggregator; `vendor/model` slugs (`:free` variants exist). Filter for tool-calling + coding models before pinning. |
497
594
  | Ollama | `curl https://ollama.com/v1/models -H "Authorization: Bearer $BKIT_OLLAMA_API_KEY"` | Hosted Ollama; cloud-tagged models (e.g. `qwen3.5:397b`, `kimi-k3`). |
498
- | OpenCode Zen / Go (opencode-native gateways) | `curl https://models.dev/api.json` — read providers `.opencode` (Zen) and `.["opencode-go"]` (Go) `.models` | **models.dev is the source of truth — not `/zen/v1/models`.** The REST catalog `curl https://opencode.ai/zen/v1/models` returns only the Zen catalog and cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`/`qwen3.7-max`, …), so it must not be used to curate the Go column. Two DISTINCT providers: `opencode` (name "OpenCode Zen", api `https://opencode.ai/zen/v1`) and `opencode-go` (name "OpenCode Go", api `https://opencode.ai/zen/**go**/v1` — nested under `/zen/`). Both auth via `BKIT_OPENCODE_API_KEY`. Tool-call smoke: `POST <api>/chat/completions` with a `tools:` payload (bare model id, e.g. `minimax-m3`). |
595
+ | OpenCode Zen / Go (OpenCode-native gateways) | `curl https://models.dev/api.json` — read providers `.opencode` (Zen) and `.["opencode-go"]` (Go) `.models` | models.dev is the source of truth, not `/zen/v1/models`. The REST catalog `curl https://opencode.ai/zen/v1/models` returns only the Zen catalog and cannot see Go-only models (`minimax-m3`, `qwen3.7-plus`/`qwen3.7-max`, …), so it must not be used to curate the Go column. Two distinct providers: `opencode` (name "OpenCode Zen", api `https://opencode.ai/zen/v1`) and `opencode-go` (name "OpenCode Go", api `https://opencode.ai/zen/**go**/v1` — nested under `/zen/`). Both auth via `BKIT_OPENCODE_API_KEY`. Tool-call smoke: `POST <api>/chat/completions` with a `tools:` payload (bare model id, e.g. `minimax-m3`). |
499
596
 
500
- **Model ID format:** opencode provider-prefixed frontmatter: `<provider>/<model-id>` (e.g. `openrouter/moonshotai/kimi-k3`, `ollama/deepseek-v4.1-flash`). Pins = `prompts.md` § Models — **one column per provider** (`OpenRouter`, `Ollama`, `OpenCode Zen`, `OpenCode Go`). Gateways: `opencode/<id>` Zen, `opencode-go/<id>` Go. CLI keys `opencode-zen` / `opencode-go`.
597
+ **Model ID format:** OpenCode provider-prefixed frontmatter: `<provider>/<model-id>` (e.g. `openrouter/moonshotai/kimi-k3`, `ollama/deepseek-v4.1-flash:1017`). Pins live in `prompts.md` § Models, one column per provider (`OpenRouter`, `Ollama`, `OpenCode Zen`, `OpenCode Go`). Gateways: `opencode/<id>` Zen, `opencode-go/<id>` Go. CLI keys: `opencode-zen` / `opencode-go`.
501
598
 
502
599
  **Lookup mechanic (install pin resolution).** `bkit install --opencode=<provider>` → `buildOpencodeModelLookup(promptsMdPath, provider)` (`.bkit/core/engine/render/models.ts`):
503
600
 
504
- 1. Provider key → `prompts.md` column via `OPENCODE_PROVIDER_COLUMN` (`openrouter`→`OpenRouter`, `ollama`→`Ollama`, `opencode-zen`→`OpenCode Zen`, `opencode-go`→`OpenCode Go`).
505
- 2. Parse column → seed `.opencode/agents/<name>.md` `model:` verbatim.
601
+ 1. Provider key → `prompts.md` column via `GATEWAY_COLUMN` (`openrouter`→`OpenRouter`, `ollama`→`Ollama`, `opencode-zen`→`OpenCode Zen`, `opencode-go`→`OpenCode Go`).
602
+ 2. Parse the column. Each cell holds the bare model id, and `formatModelPin` adds the OpenCode provider id in front (`<provider>/<model-id>`) when it writes `.opencode/agents/<name>.md` `model:`.
603
+
604
+ **OpenCode-zen / OpenCode-go — two OpenCode built-in providers.** Both emit a minimal `provider.<id>` with only `options.apiKey: "{env:BKIT_OPENCODE_API_KEY}"` (no npm driver, no baseURL). OpenCode resolves them from models.dev. Go Qwen / MiniMax use Anthropic `/messages`, not openai-compatible `/chat/completions`. Zen is keyed `opencode`, and Go `opencode-go`. `bkit install --opencode=opencode-zen` (or `=opencode-go`) → `bkit.providers.opencode.default` in `package.json`. When `package.json` names no provider, install reads it back from `.opencode/opencode.json`, and a provider block keyed `opencode` reads as `opencode-zen` (`detectOpencodeProvider`, `.bkit/core/engine/commands/install/install.ts`). Reinstall replaces the seeded block (which heals a hijacked npm / baseURL). Set `BKIT_OPENCODE_API_KEY` in `.bkit/.env` (<https://opencode.ai/auth>). The columns come from models.dev.
506
605
 
507
- **opencode-zen / opencode-go — two OpenCode built-in providers.** Both emit minimal `provider.<id>` with only `options.apiKey: "{env:BKIT_OPENCODE_API_KEY}"` (no npm driver, no baseURL). OpenCode resolves from models.dev — Go Qwen/MiniMax use Anthropic `/messages`, not openai-compatible `/chat/completions`. Zen keyed `opencode`; Go `opencode-go`. `bkit install --opencode=opencode-zen` (or `=opencode-go`) → `bkit.providers.opencode.default` in `package.json`; legacy `opencode` → `opencode-zen` via `OPENCODE_PROVIDER_ALIASES`. Reinstall **replaces** seeded block (heals hijacked npm/baseURL). Set `BKIT_OPENCODE_API_KEY` in `.bkit/.env` (<https://opencode.ai/auth>). Columns from **models.dev**.
606
+ **All four OpenCode providers ship curated columns.** The tier design is a per-tier quality target with the cheapest sufficient pin. A tier cell is not "the same rung of this provider's ladder". It is the cheapest model that reaches that tier's Claude score, and reaching means approaching: it does not have to beat it. The targets are the LiveBench 2.0 Long Agentic scores (§ LiveBench 2.0 board): opus `claude-opus-5-5` 72.8, sonnet `claude-sonnet-5-5` 63.4, haiku `claude-haiku-5-5` 40.0.
508
607
 
509
- **All four opencode providers ship curated columns.** Tier design — **per-tier quality target, cheapest sufficient pin**. A tier cell is not "the same rung of this provider's ladder": it is the cheapest model that **reaches that tier's Claude score**, and reaching means _approaching_ — it does not have to beat it. Targets are the LiveBench Agentic Coding scores on the board below (opus `claude-opus-5` **65.2**, sonnet `claude-sonnet-5` **59.4**, haiku `claude-haiku-5-5` **~51**). The opus and sonnet targets stay the 5.0 scores although the 5.5 pins are on the CSV: `claude-opus-5-5` lands level at `xhigh` (65.4), and the `claude-sonnet-5-5` rows don't read cleanly (see the board). The haiku target is Haiku 5.5 at `xhigh`, the closest measured rung to the `high` effort haiku-tier agents run at. Where a provider's ceiling sits under the sonnet target, opus+sonnet **collapse onto that ceiling** — spreading them across two rungs buys nothing and costs quality on the sonnet half. Where a cheap model already clears the haiku target, the haiku cell **stays cheap** — a $5/task flagship serving a read-and-emit summariser is waste, not safety.
608
+ - Where a provider's ceiling sits under the sonnet target, opus and sonnet collapse onto that ceiling, because spreading them across two rungs buys nothing and costs quality on the sonnet half.
609
+ - Where a cheap model already clears the haiku target, the haiku cell stays cheap, because a $5/task flagship serving a read-and-emit summariser is waste, not safety.
510
610
 
511
611
  ### Selecting pins
512
612
 
513
- Re-pin **one provider column at a time**. Cells: `prompts.md` § Models. Board below = scores.
613
+ Re-pin one provider column at a time. The cells are in `prompts.md` § Models. The board below holds the scores.
514
614
 
515
615
  **Priority — do not invert.**
516
616
 
517
- 1. **Claude parity** — LiveBench Agentic Coding (pin score) + AA Intelligence Index. Miss the target → not a pin.
518
- 2. **Cost** — cheapest that clears (or the ceiling). AA $/task + LiveBench $/task, rescaled to the billed provider.
519
- 3. **Speed** — remaining ties: AA tok/s, TTFT, think→answer, E2E 500-token.
617
+ 0. **Budget band:** a hard ceiling on what an OpenCode column may bill over a 2-day subscription gap: A$70/week default, A$140/week opt-in (§ Budget band). A pin that pushes its column past the cap is disqualified at any score.
618
+ 1. **Claude parity:** LiveBench Long Agentic (pin score) and the AA Intelligence Index. Inside the band, the model closest to the bar wins. A column whose best in-band model misses the bar records the gap.
619
+ 2. **Cost:** inside the band, the cheapest model that reaches the bar. Ties fall through to price. AA $/task and LiveBench $/task, rescaled to the billed provider.
620
+ 3. **Speed:** for remaining ties, AA tok/s, TTFT, think→answer, E2E 500-token.
520
621
 
521
- Filters (not above score): endpoint count; automatic prompt caching (bkit sends no `cache_control`). **Never pin Claude** on OpenRouter / Ollama / OpenCode. Convergent = distinct CoT family, not a fourth rung.
622
+ **Filters** (not above score): endpoint count, and automatic prompt caching (bkit sends no `cache_control`). Any vendor may pin on an OpenCode column. The budget band, not a vendor list, is what keeps the costliest models off.
522
623
 
523
624
  **Steps.**
524
625
 
525
- 1. Read `prompts.md` § Models + lineup below.
526
- 2. Pull every source; stamp the date. LiveBench `table_<date>.csv` name != freshness.
527
- 3. Slug live? § Per-provider live model lookup. OpenRouter: also `GET /api/v1/models/{slug}/endpoints`.
528
- 4. Shortlist 1-2 / tier. Reject single-endpoint + `cache_control` hosts (Anthropic, Alibaba) unless no alternative.
529
- 5. Apply: `prompts.md` § Models + this board + `.bkit/core/engine/render/models.test.ts` OpenRouter tests + `bkit install`. Stamp `prompts.md` § Live model-ID verification.
626
+ 1. Read `prompts.md` § Models and the lineup below.
627
+ 2. Pull every source, and stamp the date. A LiveBench `table_<date>.csv` name != freshness.
628
+ 3. Check the slug is live: § Per-provider live model lookup. For OpenRouter, also `GET /api/v1/models/{slug}/endpoints`.
629
+ 4. Shortlist 1-2 per tier. Reject single-endpoint and `cache_control` hosts (Anthropic, Alibaba) unless there is no alternative.
630
+ 5. Apply to `prompts.md` § Models, this file's § LiveBench 2.0 board and § Per-tier lineup across providers, and the `.bkit/core/engine/render/models.test.ts` OpenRouter tests, and run `bkit install`. Stamp `prompts.md` § Live model-ID verification.
530
631
 
531
632
  **Sources — check all.**
532
633
 
533
634
  <!-- prettier-ignore -->
534
635
  | Pri | Source | Decides | URL |
535
636
  | --- | --- | --- | --- |
536
- | 1 | LiveBench Agentic Coding | Pin score (JS / TS / PY mean) | https://livebench.ai/#/?cats=Agentic+Coding — CSV `https://raw.githubusercontent.com/LiveBench/new-livebench/main/public/table_2026_06_25.csv` |
637
+ | 1 | LiveBench 2.0 | Pin score — Long Agentic | `https://livebench.ai/data/<YYYYMMDD>/table.csv`, beside it `categories.json` (category → columns + `_overall_weights`), `cost.csv`, `breakdown.json`. Releases `20261014`, `20261025` (latest `20261025`). The v1 path is dead: `raw.githubusercontent.com/LiveBench/new-livebench/…/public/table_<date>.csv` 404s for 2.0 and stops at `2026-06-25` |
537
638
  | 1 | AA Intelligence Index | General intelligence | https://artificialanalysis.ai/leaderboards/models |
538
639
  | 1 | DeepSWE | Long-horizon repo work — public board only | https://deepswe.datacurve.ai |
539
640
  | 1 | LMArena Code Arena — WebDev | Web-dev preference | https://lmarena.ai (Code / WebDev) |
540
641
  | 1 | Design Arena — Code | Web-app preference | https://designarena.ai/leaderboard/code |
541
- | 1 | CursorBench | Agentic coding at **every effort level** (`low` → `max`) with $/task — the source for choosing an agent's `effort:`; cross-checks LiveBench. Cursor's own `composer-*` rows count as vendor-only | https://cursor.com/cursorbench |
642
+ | 1 | CursorBench | Agentic coding at every effort level (`low` → `max`) with $/task. The source for choosing an agent's `effort:`; cross-checks LiveBench. Cursor's own `composer-*` rows count as vendor-only | https://cursor.com/cursorbench |
542
643
  | 2-3 | AA cost / latency | $/task, tok/s, TTFT, E2E | same AA leaderboard |
543
- | 2 | LiveBench cost table | Agentic $/task — rescale to billed provider | `cost_2026_06_25.csv` beside the LiveBench table |
544
- | 2 | OpenRouter model page | List in/out + cache-read | https://openrouter.ai/models/{slug} |
644
+ | 2 | LiveBench cost table | $/task per category — `out_<category>` = dollars per successful task; rescale to billed provider | `https://livebench.ai/data/<YYYYMMDD>/cost.csv` |
645
+ | 2 | OpenRouter model page | List in / out + cache-read | https://openrouter.ai/models/{slug} |
545
646
  | filter | OpenRouter endpoints | Host count; 1 = reject | `GET /api/v1/models/{slug}/endpoints` |
546
647
  | filter | OpenRouter prompt-caching doc | Auto vs `cache_control`; ignore `supports_implicit_caching` | https://openrouter.ai/docs/features/prompt-caching |
547
648
  | filter | Provider catalogs | Existence / context / plan gates | § Per-provider live model lookup |
548
649
 
549
650
  **Do not pin from:** OpenRouter volume; BenchGecko; vendor-only Terminal-Bench / SWE; launch blogs.
550
651
 
551
- ### Agentic-coding parity board
652
+ **Four column classes — each answers a different question.**
552
653
 
553
- Source: [LiveBench](https://livebench.ai/#/?cats=Agentic+Coding), release **2026-06-25** (`table_2026_06_25.csv` / `cost_2026_06_25.csv`, `LiveBench/new-livebench`). **Score** = mean of the category's three tasks (`javascript`, `typescript`, `python`), per `public/categories_<date>.json`. **$/task** = category dollars ÷ 72 questions, from LiveBench's own cost table. Process + sources: § Selecting pins. Artificial Analysis stays the source for price/latency and general capability; agentic-coding score decides a **pin**, because that is the workload every bkit agent runs.
654
+ <!-- prettier-ignore -->
655
+ | Class | Columns | What the pin answers |
656
+ | --- | --- | --- |
657
+ | First-party plan | `Anthropic` (Claude), `OpenAI` (Codex), `Google` (Antigravity) | The best model for each subagent from that vendor's own ladder, spending the plan's included usage where it buys the most. A Codex pin is the best OpenAI model for the job, never an imitation of Claude; no cross-vendor parity target. |
658
+ | Metered gateway | `Ollama`, `OpenCode Zen`, `OpenCode Go` | Claude is the yardstick: the cheapest model in that gateway's catalog closest to the agent's Claude tier bar, inside the budget band. Any vendor qualifies. |
659
+ | Overflow default | `OpenRouter` Option 1 | OpenRouter runs on the days the OpenAI, Anthropic and Google credits are spent. Same yardstick; the default spends the A$70 cap on `gpt-6.1-sol` for the four key gates and runs every other agent on `deepseek-v4.1-flash-1017`. |
660
+ | Overflow opt-in | `OpenRouter` Option 2 | Doubles the weekly cap to A$140, which buys nine judges on `gpt-6.1-sol`. |
661
+
662
+ **The question is per subagent, not per column.** Every pin answers "what is the best model for this agent's job", judged on the board's Long Agentic score with the agent's role in mind. Judges, reviewers, verifiers and escalators need the strongest model the class allows (see the reviewer rule below). Mechanical writers and summarisers should not pay flagship prices. Matching cells across columns are a catalog coincidence, never an objective.
554
663
 
555
- **Re-probe on a schedule, never on a release stamp.** LiveBench appends newly released models to the **existing** `table_<date>.csv` — `RELEASES` in its `src/lib/constants.js` stays put while the file's contents move. The cited date is not a freshness signal, and a column can go stale with nothing here looking stale.
664
+ ### Budget band — the gap between subscription resets
556
665
 
557
- **$/task must be rescaled to the provider actually billed.** LiveBench's cost table assumes direct-vendor pricing; an OpenRouter pin is billed at OpenRouter's `pricing.prompt` / `pricing.completion`. The two diverge (LiveBench assumes `$3/$15` per Mtok for `claude-sonnet-5`; OpenRouter charges `$2/$10`). Solve LiveBench's dollar figure for implied input tokens, then re-price.
666
+ **Usage intent.** An OpenCode column runs between subscription resets: after the week's Claude and OpenAI credits are gone, until they return. Days, not a month. A pin that would burn a month's worth of cost inside such a gap fails its purpose however well it scores, so cost is a ceiling checked before parity, not a tie-break after it.
558
667
 
559
- **Sub-scores are too coarse to pin on; use them to sanity-check, not to decide.** Question counts are JS 22 / TS 30 / PY 20, so one TypeScript question moves that sub-score 3.33 points (SE ~ 9). TypeScript is the hardest of the three and every model scores below its own mean there — the Claude ladder is **not monotonic on TypeScript** (`claude-sonnet-5` 50.0 sits above `claude-opus-5` 43.3). Read the mean as the pin criterion; do not read it as a ranking of ability in any one language.
668
+ **The band is a cache-read ceiling, because cache reads are the bill.** Measured across 21 days of real agent work (Claude transcripts, deduped by message), a normal day carries ~1.0-1.2B cache-read tokens, ~20M cache writes, ~1.6-2.4M output and ~0 fresh input. That is roughly 600 cache-read tokens per output token, so cache reads exceed 95% of what a gap costs. Cache-read price spans ~170x across the board while input price spans ~13x, so an input / output band cannot predict what a gap costs.
560
669
 
561
- **Score is necessary, not sufficient — operational shape decides ties.** Two properties carry real weight once scores are within noise: **endpoint count** (`/api/v1/models/<slug>/endpoints`) and **whether prompt caching applies without client configuration**. A single-endpoint model cannot be routed around a slow or down host and inherits that one provider's rate limits — disqualifying for a column whose whole job is to absorb work when the Claude quota is spent. Caching is the dominant latency and cost term for bkit workloads: without it every turn of a long agentic loop re-prefills the whole growing transcript.
670
+ **Measured on OpenCode itself** (`bkit harvest scan`, 2026-10-25 → 10-28, 166 chats on `deepseek-v4.1-flash`): a heavy day carries 27.8M fresh input, 1.04B cache read and 2.08M output. The fresh input is what the Claude profile misses, because Claude caches almost all of it away and OpenCode does not. Per heavy day at list prices: DeepSeek $8.6, Gemini 4 Argon or GPT-6.1 Sol $180.8, Claude Opus 5.5 $361.5. Input price therefore matters on this profile: the Gemini / GPT tier spends $56 of its $181 on fresh input alone.
562
671
 
563
- **Read caching from the provider docs, not from `supports_implicit_caching`.** That endpoint field is unreliable — it reports `false` on all 14 `kimi-k3` endpoints while OpenRouter's own [prompt-caching doc](https://openrouter.ai/docs/features/prompt-caching) states Moonshot caching is automated. The doc's per-provider sections are authoritative. Current contracts: **Moonshot, DeepSeek, Z.AI, Gemini 2.5+ cache automatically, no configuration**; **Anthropic, Alibaba Qwen require explicit `cache_control` breakpoints**, which bkit does not send — so an Alibaba-hosted pin gets no caching at all. Cache reads run ~0.03x-0.20x of input price; writes are free except on DeepSeek (charged at input price).
672
+ **What the A$70 cap buys on that day** (A$0.703/USD, 2-day gap, day cost split evenly over 40 agents): `gpt-6.1-sol` costs about A$13.16 per agent per gap, and `deepseek-v4.1-flash-1017` A$0.62.
564
673
 
565
- **Cache hits need the same endpoint twice — OpenRouter handles this with sticky routing.** After a cached request it pins the conversation to that provider, keyed by `session_id` / `prompt_cache_key` when sent, otherwise by hashing the first system message plus the first non-system message. Sticky sessions expire after **10 minutes of inactivity**, and sticky routing is disabled entirely when `provider.order` is set — do not pin a provider order on a cached model.
674
+ - All 40 on DeepSeek: A$25.
675
+ - Four on sol, the rest on DeepSeek: A$74. That is A$4 over, and accepted.
676
+ - A$140 buys nine on sol (A$137). All twelve judges land at A$175 and breach it.
566
677
 
567
678
  <!-- prettier-ignore -->
568
- | Model | Score | $/task | Role in bkit |
679
+ | Cache-read ceiling (per Mtok) | Normal day | 2-day gap | Models that survive |
569
680
  | --- | --- | --- | --- |
570
- | `deepseek-v4.1-flash` | **77.3** | $0.06 | every opencode column's opus+sonnet — 16+ OpenRouter endpoints, auto cache; clears 65.2. Haiku on `ollama` + `opencode-go` |
571
- | `claude-opus-5-5` (max) | 71.7 | $4.48 | Claude opus pin at `max` |
572
- | `claude-opus-5-5` (xhigh) | 65.4 | $1.40 | Claude opus pin at `xhigh` — level with the opus target at about a quarter of the cost |
573
- | `claude-opus-5` (max) | **65.2** | $5.34 | **opus target** |
574
- | `deepseek-v4-flash-vision-exp` | 65.1 | $0.11 | **not pinned** — experimental; its own datasheet claims text parity with `deepseek-v4-flash-0731`, which measures 46.8. Score not trusted |
575
- | `qwen3.8-max` | 64.6 | $1.75 | **not pinned** — single endpoint (Alibaba) and **no caching available**: Alibaba requires explicit breakpoints and this slug is absent from its supported list |
576
- | `kimi-k3` | 62.2 | $1.76 | every opencode column's convergent — 17 OpenRouter endpoints, auto cache (reads 0.10x, writes free); both gateways bill $3/$15 per Mtok |
577
- | `claude-fable-5` (max) | 62.2 | $8.86 | not adopted — below Opus 5 at 1.7x the cost |
578
- | `qwen3.8-27b` | 61.4 | $1.52 | **not pinned** — 3.57M input tokens/task; `$0.95` on LiveBench's assumed price, `$1.52` at OpenRouter's |
579
- | `glm-5.3` | 60.9 | $1.60 | **not pinned** — 27 endpoints, auto cache; dominated by V4.1 Flash |
580
- | `claude-sonnet-5` (xhigh) | **59.4** | $2.14 | **sonnet target** |
581
- | `gemini-3.7-flash` | 58.3 | $0.42 | **not pinned** — under V4.1 Flash |
582
- | `claude-haiku-5-5` (max) | 57.2 | $0.21 | Claude haiku pin at `max` |
583
- | `grok-4.6` | 57.0 | $1.79 | **not pinned** — under V4.1 Flash, higher cost |
584
- | `glm-5.3-flash` | 56.8 | $0.11 | `openrouter` + `opencode-zen` haiku — 27 endpoints, auto cache; cheapest sufficient |
585
- | `grok-4.5` | 56.5 | $0.54 | `cursor` opus (ceiling; −2.9 vs sonnet target at a quarter the cost) |
586
- | `claude-sonnet-5-5` (max) | 56.3 | $5.57 | Claude sonnet pin at `max`. Python 35.0 at both efforts (n=20) |
587
- | `deepseek-v4-pro-0813` | 54.9 | $0.22 | **not pinned** — dominated by V4.1 Flash |
588
- | `claude-haiku-5-5` (xhigh) | **51.4** | $0.07 | **haiku target** — closest measured rung to bkit's `high` (CursorBench: `high` 42.3%, `xhigh` 44.3%) |
589
- | `gpt-6-luna` | 51.2 | $0.03 | `OpenAI` (Codex) haiku — existence via models.dev only |
590
- | `claude-opus-4-8` (max) | 50.5 | $4.96 | superseded — shows the 4.8 → 5 generational jump (+14.7) |
591
- | `kimi-k2.7-code` | 45.7 | $0.39 | **not pinned** — dominated by `deepseek-v4.1-flash` (77.3 · $0.06) on every column that carries both |
592
- | `qwen3.7-max` | 43.6 | $0.80 | not pinned (anchor for the unmeasured `qwen3.7-plus`) |
593
- | `deepseek-v4-pro` | 42.6 | $0.14 | **not pinned** — dominated by V4.1 Flash. **Frozen on the 0423 snapshot** — the undated slug does not float |
594
- | `qwen3.6-plus` | 41.4 | $1.55 | **not pinned** — strictly dominated by `kimi-k2.7-code` (lower score, 4x cost) |
595
- | `minimax-m3` | 40.7 | $0.42 | **not pinned** — `deepseek-v4-pro` scores higher at a third the cost |
596
- | `claude-sonnet-5-5` (xhigh) | 39.3 | $0.50 | **not read as a target** — Anthropic recalibrated effort on 5.5, and this run wrote about half Sonnet 5's output tokens before stopping. CursorBench, Artificial Analysis and Anthropic all put 5.5 above 5 at every effort |
597
- | `deepseek-v4-flash` | 37.6 | **$0.03** | **not pinned** — under the ~51 haiku target |
598
- | `claude-haiku-4-5` (thinking) | ~35 † | — | not pinned — under the ~51 haiku target |
599
- | `gpt-oss-120b` | ~10 † | — | **pinned nowhere** — below every target, haiku included |
600
-
601
- † **Estimated, not measured.** Model absent from the 2026-06-25 release; value bridged from its 2026-01-08 score via the mean delta of the three nearest-scoring models present in both releases. Cross-release scores are not comparable directly (LiveBench rotates questions — overlapping models moved −1.4 to −31.5), so treat † as a bracket, not a number. **Unmeasured entirely** (no anchor in either release, do not infer): `composer-2.5`, `qwen3.5-397b`, `qwen3-coder`, `qwen3.7-plus`, `glm-4.5-air`, `gpt-oss-20b`, `qwen3-coder:30b`.
681
+ | <= `$0.005` | ~$8 | ~$30 | `deepseek-v4.1-flash-1017` ($0.003) |
682
+ | <= `$0.015` | ~$17 | ~$60 | + `minimax-m3.1-flash` ($0.015) |
683
+ | <= `$0.04` | ~$47 | ~$150 | + `glm-5.3-flash` ($0.03) |
684
+ | <= `$0.10` | ~$105 | ~$240 | + `gemini-4-argon` ($0.10), `gpt-6.1-sol` ($0.10) |
685
+ | <= `$0.20` | ~$200 | ~$500 | + `kimi-k3.1-pro` ($0.20), `kimi-k3` ($0.19) |
686
+
687
+ `grok-4.7` ($0.50 cache read) fails every row. **No single ceiling binds the column:** the cap is spent as a mix. The `$0.005` row covers most agents, and the `$0.10` row covers as many judges as the remaining cap carries (§ LiveBench 2.0 board, Two presets).
688
+
689
+ Cache-read prices on the current pins: `deepseek-v4.1-flash` $0.003, `glm-5.3-flash` $0.03 (haiku), `gpt-6.1-sol` and `gemini-4-argon` $0.10 (key gates).
690
+
691
+ ### LiveBench 2.0 board — 2026-10-25
692
+
693
+ Re-probed `https://livebench.ai/data/20261025/table.csv` + `cost.csv` (§ Selecting pins § Sources). **Pin score** = Long Agentic: 2.0's headline category, weighted 2x in the overall, and the multi-turn long-horizon work every agent runs. **Coding** = a sanity check, never the criterion. 2.0 replaced v1's single Agentic Coding category with seven, each its own task set, so v1 and 2.0 scores do not convert. Never carry a v1 number forward or bridge across the gap.
694
+
695
+ **Bars (Claude, 2.0):** opus `claude-opus-5.5` 72.8 · sonnet `claude-sonnet-5.5` 63.4 · haiku `claude-haiku-5.5` 40.0. All three are measured on this release: no bridging, no held-over 5.0 rows.
696
+
697
+ <!-- prettier-ignore -->
698
+ | Model | Long Agentic (pin) | Coding | Overall | LA $/task | OR endpoints | Pinnable on |
699
+ | --- | --- | --- | --- | --- | --- | --- |
700
+ | `claude-fable-5.1` | **77.9** | 97.7 | 85.7 | $928.31 | — | — (Claude) |
701
+ | `gpt-6-astra` | **77.5** | 93.7 | 85.6 | $690.82 | 7 | or · zen |
702
+ | `claude-opus-5.5` | **72.8** | 96.3 | 85.1 | $684.16 | — | **opus bar** |
703
+ | `gpt-6.1-sol` | **68.7** | 96.0 | 84.1 | $116.78 | 8 | or · zen |
704
+ | `claude-sonnet-5.5` | **63.4** | 94.7 | 80.0 | $630.21 | — | **sonnet bar** |
705
+ | `gemini-4-argon` | **61.2** | 89.7 | 79.3 | $249.15 | 6 | or · zen · go |
706
+ | `muse-wonder-1.0` | **52.6** | 86.2 | 74.2 | $249.07 | — | or · zen |
707
+ | `gpt-6.1-terra` | **48.6** | 94.3 | 77.8 | $116.42 | 4 | or |
708
+ | `grok-4.7` | **46.1** | 84.5 | 70.1 | $337.79 | 5 | or · zen · go |
709
+ | `deepseek-v4.1-flash-1017` | **40.9** | 96.0 | 74.0 | $25.96 | 36 | or · ollama |
710
+ | `claude-haiku-5.5` | **40.0** | 91.4 | 69.8 | $188.84 | — | **haiku bar** |
711
+ | `kimi-k3.1-pro` | **39.1** | 81.8 | 71.3 | $133.67 | 2 | or · go |
712
+ | `mimo-v2.6-pro` | **35.2** | 81.5 | 68.5 | $21.86 | 5 | or · go |
713
+ | `gpt-5.6-terra` | **33.1** | 86.2 | 67.8 | $211.62 | 7 | or |
714
+ | `gpt-6-luna` | **30.9** | 84.5 | 64.6 | $17.42 | 7 | or · zen · go |
715
+ | `qwen3.8-max` | **29.9** | 60.3 | 61.6 | $268.74 | 2 | or · zen · go |
716
+ | `minimax-m3.1-flash` | **28.8** | 83.9 | 66.9 | $19.50 | 12 | or · go · ollama |
717
+ | `grok-4.6` | **28.0** | 89.1 | 67.8 | $184.39 | 6 | or · zen |
718
+ | `kimi-k3` | **26.4** | 59.3 | 64.6 | $323.83 | 30 | or · zen · go · ollama |
719
+ | `muse-spark-1.3` | **25.5** | 90.2 | 63.0 | $160.10 | — | or · zen |
720
+ | `qwen3.8-27b` | **20.6** | 86.8 | 58.4 | $111.08 | — | or |
721
+ | `step-5-preview` | **19.4** | 85.6 | 58.6 | $162.98 | 3 | or · go |
722
+ | `glm-5.3-flash` | **19.0** | 80.6 | 62.1 | $29.32 | 38 | or · zen · go · ollama |
723
+ | `gemini-3.8-flash` | **16.5** | 82.2 | 59.2 | $126.70 | 7 | or · zen |
724
+
725
+ **`gpt-6.1-sol` is the only model over the sonnet bar the cap carries.** It pins the four key gates on `openrouter` and `opencode-zen`. `gpt-6-astra` (77.5) bills ~6x sol per task ($690.82) and stays on the `OpenAI`/Codex judges. The Claude rows bill more still.
726
+
727
+ **One release is a weak signal.** `kimi-k3` read 42.8 on `20261014` and 26.4 on `20261025` for the same category, so a re-pin takes a second release as corroboration unless the gap exceeds the bar's margin. `$` is LiveBench's own direct-vendor basis. A gateway pin is billed at the gateway's price (Zen `deepseek-v4.1-flash` $0.30/$1.20, Go $0.15/$0.60, `gemini-4-argon` $2/$10 on both gateways).
728
+
729
+ **Unmeasured on 2.0:** `composer-2.5` and `cursor-grok-4.5-high` (Cursor), `gemini-3.8-pro` (Google / Antigravity). Their pins are catalog choices, not scored ones.
730
+
731
+ **Two presets, one budget.**
732
+
733
+ - **Judges** = the 12 reviewers, verifiers and escalators (`prompts.md` § Models, Judges note).
734
+ - **Builders** = the other 27.
735
+ - **Key gates** = the 4 judges where a miss passes downstream unchecked.
736
+
737
+ The overflow column is capped against a Max subscription, A$300/month, about A$70/week, using the 2-day gap as the binding case. Option 1, the shipped default (A$74 per gap), runs `gpt-6.1-sol` on the four key gates and `deepseek-v4.1-flash-1017` everywhere else. Option 2 (A$137) runs sol on nine judges. Reviewers must out-rank builders wherever the budget allows. That rule binds Option 2 and any consumer who raises the cap. The preset tables, the per-agent matrix, the unpriced costs and the Option 2 copy-paste block are in `prompts.md` § Model Presets.
738
+
739
+ **FX:** A$0.703/USD on 2026-10-27. The caps are weekly. A 2-day gap is the binding case at the measured profile.
740
+
741
+ **Why the presets sit above `bkit:end`:** a consumer's § Model Overrides below it is preserved by install and upgrade, so text placed there would never reach an existing install. That consumer region stays deliberately thin: a usage line and the empty table.
742
+
743
+ ### Endpoint and caching checks
744
+
745
+ **Re-probe on a schedule, never on a release stamp.** LiveBench appends newly released models to the existing `table_<date>.csv`, and `RELEASES` in its `src/lib/constants.js` stays put while the file's contents move. The cited date is not a freshness signal, and a column can go stale with nothing here looking stale.
746
+
747
+ **$/task must be rescaled to the provider actually billed.** LiveBench's cost table assumes direct-vendor pricing. An OpenRouter pin is billed at OpenRouter's `pricing.prompt` / `pricing.completion`. The two diverge (LiveBench assumes `$3/$15` per Mtok for `claude-sonnet-5`; OpenRouter charges `$2/$10`). Solve LiveBench's dollar figure for implied input tokens, then re-price.
748
+
749
+ **A score is necessary, not sufficient — operational shape decides ties.** Two properties carry real weight once scores are within noise: endpoint count (`/api/v1/models/<slug>/endpoints`), and whether prompt caching applies without client configuration. A single-endpoint model cannot be routed around a slow or down host, and inherits that one provider's rate limits. That disqualifies it for a column whose whole job is to absorb work when the Claude quota is spent. Caching is the dominant latency and cost term for bkit workloads: without it, every turn of a long agentic loop re-prefills the whole growing transcript.
750
+
751
+ **Read caching from the provider docs, not from `supports_implicit_caching`.** That endpoint field is unreliable. It reports `false` on every `kimi-k3` endpoint, while OpenRouter's own [prompt-caching doc](https://openrouter.ai/docs/features/prompt-caching) states Moonshot caching is automated. The doc's per-provider sections are authoritative. Current contracts:
752
+
753
+ - Moonshot, DeepSeek, Z.AI, Gemini 2.5+ cache automatically, with no configuration.
754
+ - Anthropic, Alibaba Qwen require explicit `cache_control` breakpoints, which bkit does not send, so an Alibaba-hosted pin gets no caching at all.
755
+
756
+ Cache reads run ~0.03x-0.20x of input price. Writes are free except on DeepSeek (charged at input price).
757
+
758
+ **Cache hits need the same endpoint twice — OpenRouter handles this with sticky routing.** After a cached request it pins the conversation to that provider, keyed by `session_id` / `prompt_cache_key` when sent, otherwise by hashing the first system message plus the first non-system message. Sticky sessions expire after 10 minutes of inactivity, and sticky routing is disabled entirely when `provider.order` is set. Do not pin a provider order on a cached model.
602
759
 
603
760
  ### Per-tier lineup across providers
604
761
 
605
- Cells show pin · score · $/task. Deltas are against that column's target. Convergent (CoT lens for risk/diagnosis agents) rides the same board.
762
+ Cells show pin · score · $/task. Deltas are against that column's target. Key gates (the 4 judges named in `prompts.md` § Models) ride the same board.
606
763
 
607
764
  <!-- prettier-ignore -->
608
- | Provider | opus — target 65.2 | sonnet — target 59.4 | haiku — target ~51 | convergent | Notes |
765
+ | Provider | opus — target 72.8 | sonnet — target 63.4 | haiku — target 40.0 | key gates | Notes |
609
766
  | --- | --- | --- | --- | --- | --- |
610
- | `claude` | `claude-opus-5-5` 65.4 at `xhigh` | `claude-sonnet-5-5` (see board) | `claude-haiku-5-5` at `high` (51.4 at `xhigh`) | (opus) | Pins are 5.5 ($4/$20 opus, $2/$10 sonnet, $0.10/$0.50 haiku, 1M context). Opus and sonnet targets stay the 5.0 scores (`claude-opus-5` **65.2** · $5.34, `claude-sonnet-5` **59.4** · $2.14): Opus 5.5 lands level at `xhigh`, and Sonnet 5.5's LiveBench rows don't read cleanly. Haiku target = Haiku 5.5 at `xhigh`. |
611
- | `openrouter` | `deepseek/deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `z-ai/glm-5.3-flash` 56.8 · $0.11 (+5.4) | `moonshotai/kimi-k3` 62.2 · $1.76 | Aggregator; broad catalog to re-pin from. Opus+sonnet collapse on V4.1 Flash (clears 65.2). Haiku = GLM-5.3 Flash (cheapest sufficient). Convergent = Kimi K3 (distinct CoT). All three auto-cache. Never pin `anthropic/*` — column carries Claude-quota overflow. |
612
- | `cursor` | `cursor-grok-4.5-high` 56.5 · $0.54 (−8.7) | `composer-2.5` **n/m** | `composer-2.5` **n/m** | (opus) | Ceiling is grok-4.5 — no Cursor model reaches the opus target, which is the correct outcome, not a gap. `composer-2.5` is the one unresolved cell in the matrix: vendor-claimed ~ Opus 4.7 (which measures 50.7), never on LiveBench. Probe or override before relying on it for sonnet-tier work. Haiku stays `composer-2.5` too: the only measured first-party model over ~51 is `cursor-grok-4.5-high` (56.5), at about 8x the cost. |
613
- | `ollama` (cloud) | `deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `deepseek-v4.1-flash` 77.3 · $0.06 (+25.9) | `kimi-k3` 62.2 · $1.76 | **Whole column needs a paid Ollama plan.** **No model variants** — the ollama provider builds catalog entries with none, so bkit omits `variant:` on this column (2.0 would reject it); agents run at opencode's default reasoning. Opus+sonnet+haiku collapse on V4.1 Flash (clears 65.2); convergent = Kimi K3 (distinct CoT), matching `openrouter`. The free `qwen3.5:397b` / `gpt-oss:20b` are unmeasured or ~10 — free-tier users re-pin in `prompts.md` § Model Overrides and accept unverified quality. |
614
- | `opencode-zen` | `opencode/deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `opencode/glm-5.3-flash` 56.8 · $0.11 (+5.4) | `opencode/kimi-k3` 62.2 · $1.76 | Opus+sonnet re-pinned from `kimi-k2.7-code` (45.7 · $0.39): 2.0 hard-errors on a `variant:` the model does not expose, and `kimi-k2.7-code` exposes none. V4.1 Flash clears 65.2 and carries variants; **Zen bills it at $0.30/$1.20** (higher than the LiveBench $/task shown). Haiku = GLM-5.3 Flash. Convergent = Kimi K3 (distinct CoT), billed $3/$15. Existence-validated via models.dev. |
615
- | `opencode-go` | `opencode-go/deepseek-v4.1-flash` 77.3 · $0.06 (+12.1) | same (+17.9) | `opencode-go/deepseek-v4.1-flash` 77.3 · $0.06 (+25.9) | `opencode-go/kimi-k3` 62.2 · $1.76 | Budget open-weight plan. Convergent = Kimi K3 (distinct CoT) at $3/$15 per Mtok — the heaviest draw on the 5h window. `minimax-m3`/`qwen3.7-plus` not pinned (see the board). Prefer pins inside the Go 5h window. DeepSeek models need the workspace privacy setting on "Global regions". |
767
+ | `claude` | `claude-opus-5-5` 72.8 — the bar | `claude-sonnet-5-5` 63.4 — the bar | `claude-haiku-5-5` 40.0 — the bar | (opus) | Pins are 5.5 ($4/$20 opus, $2/$10 sonnet, $0.10/$0.50 haiku, 1M context). Targets are the 5.5 scores on the 2.0 board: `claude-opus-5-5` **72.8**, `claude-sonnet-5-5` **63.4**, `claude-haiku-5-5` **40.0**. |
768
+ | `openrouter` | `deepseek/deepseek-v4.1-flash-1017` 40.9 · $25.96 (-31.9) | same (-22.5) | `z-ai/glm-5.3-flash` 19.0 · $29.32 (-21.0) | `openai/gpt-6.1-sol` 68.7 · $116.78 (-4.1) | Aggregator; broad catalog to re-pin from. Opus+sonnet collapse on V4.1 Flash (the 40.9 workhorse sits 31.9 under the 72.8 opus bar). **Dated `1017` snapshot pinned** — the undated alias is frozen on the 2026-09-10 snapshot and does not float. Haiku = GLM-5.3 Flash — 21.0 under the bar and dearer per task than V4.1 Flash ($29.32 vs $25.96); no agent runs the haiku tier. Key gates = GPT-6.1 Sol, the only model over the sonnet bar the cap carries (§ Budget band). V4.1 Flash and GLM-5.3 Flash auto-cache. |
769
+ | `cursor` | `cursor-grok-4.5-high` **n/m** | `composer-2.5` **n/m** | `composer-2.5` **n/m** | (opus) | Ceiling is grok-4.5 — no Cursor model reaches the opus target, which is the correct outcome, not a gap. `composer-2.5` is the one unresolved cell in the matrix: vendor-claimed ~ Opus 4.7, never on LiveBench. Probe or override before relying on it for sonnet-tier work. Haiku stays `composer-2.5` too, because `cursor-grok-4.5-high` costs about 8x as much and neither is measured on 2.0. |
770
+ | `ollama` (cloud) | `deepseek-v4.1-flash:1017` 40.9 · $25.96 (-31.9) | same (-22.5) | `deepseek-v4.1-flash:1017` 40.9 · $25.96 (+0.9) | `deepseek-v4.1-flash:1017` 40.9 · $25.96 (-31.9) | **Whole column needs a paid Ollama plan.** **No model variants** — the ollama provider builds catalog entries with none, so bkit omits `variant:` on this column (2.0 would reject it); agents run at OpenCode's default reasoning. Every tier and the key gates collapse on V4.1 Flash (the 40.9 workhorse sits 31.9 under the 72.8 opus bar) — nothing stronger in the catalog. The free `qwen3.5:397b` / `gpt-oss:20b` are unmeasured — free-tier users re-pin in `prompts.md` § Model Overrides and accept unverified quality. |
771
+ | `opencode-zen` | `opencode/deepseek-v4.1-flash` **n/m** | same | `opencode/glm-5.3-flash` 19.0 · $29.32 (-21.0) | `opencode/gpt-6.1-sol` 68.7 · $116.78 (-4.1) | Opus+sonnet skip `kimi-k2.7-code` (unmeasured on 2.0): OpenCode 2.0 hard-errors on a `variant:` the model does not expose, and `kimi-k2.7-code` exposes none. The undated V4.1 Flash slug is the 2026-09-10 snapshot (models.dev `release_date`), not the `1017` refresh the 40.9 board row measures. It carries variants (`low/high/max`); **Zen bills it at $0.30/$1.20**. Haiku = GLM-5.3 Flash. Key gates = GPT-6.1 Sol. Existence-validated via models.dev. |
772
+ | `opencode-go` | `opencode-go/deepseek-v4.1-flash` **n/m** | same | `opencode-go/deepseek-v4.1-flash` **n/m** | `opencode-go/gemini-4-argon` 61.2 · $249.15 (-11.6) | Budget open-weight plan. V4.1 Flash is the undated 2026-09-10 snapshot, as on Zen. Key gates = Gemini 4 Argon — Go serves no GPT-6.1 Sol; Argon is its strongest model under the cap. `minimax-m3`/`qwen3.7-plus` are not pinned: neither is measured on the 2.0 board. Prefer pins inside the Go 5h window. DeepSeek models need the workspace privacy setting on "Global regions". |
616
773
 
617
- **n/m** = not measured on LiveBench (see the unmeasured list above) — the cell is a catalog/constraint choice, not a scored one.
774
+ **n/m** = not measured on LiveBench (see the unmeasured list above). The cell is a catalog / constraint choice, not a scored one.
618
775
 
619
- **Hard-constraint escape hatch.** "Cheapest that reaches the target" is bounded by constraints that are not about quality: paid-plan gating (`ollama`), 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.
776
+ **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.
620
777
 
621
- Cloud OpenAI-compatible cells tool-call-smoked (`tools:` round-trip `tool_calls`) — `/models` != proof (validate-with-real-tool). `opencode-zen` existence-validated via models.dev (Zen balance zero; smoke on Go endpoint). Re-pin: edit agent `model:`, add `prompts.md` § Model Overrides row, or change column + `bkit check`. Probe live catalog first (models.dev opencode; `/v1/models` table rest).
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).
622
779
 
623
- **Consumer model overrides (upgrade-safe):** `.bkit/prompts.md` marker-managed (`rules.md` pattern) — bkit refreshes `bkit:start`/`bkit:end` on upgrade; `## Model Overrides` below `bkit:end` consumer-owned. Pin different model per agentxhost/provider:
780
+ **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:
624
781
 
625
782
  ```
626
783
  | Prompt | Provider | Model |
627
784
  | --- | --- | --- |
628
- | bkit-build-plan-verify | openrouter | openrouter/deepseek/deepseek-v4-pro |
785
+ | bkit-plan-review-2 | openrouter | openai/gpt-6.1-sol |
629
786
  ```
630
787
 
631
- `Provider` = host/install key (`cursor`, `openrouter`, `ollama`, …). Install merges overrides over defaults (override wins). Claude reads frontmatter; not overridable via table yet.
788
+ `Provider` = host / install key (`cursor`, `openrouter`, `ollama`, …). Install merges overrides over defaults (the override wins). Claude reads frontmatter, and is not overridable via the table yet.
632
789
 
633
- **Cursor API-credit restore:** when you have third-party / additional API credits and want Claude Opus on Cursor workflows, use the paste block in `prompts.md` § Model Overrides (Claude-opus-tier → `claude-opus-5-thinking-high`) — that is the only way to close the −8.7 opus gap on Cursor. Sonnet-tier agents stay on shipped Composer/Grok (correct under per-tier targeting, not a shortfall) unless you opt into `gpt-5.6-sol-high`. Orchestrators `/design` `/plan` `/debug` = session model (set at launch), not the override table.
790
+ **Cursor API-credit restore:** when you have third-party / additional API credits and want Claude Opus on Cursor workflows, use the paste block in `prompts.md` § Model Overrides (Claude-opus-tier → `claude-opus-5-thinking-high`). That is the only way to put a Claude opus-tier model on Cursor (the first-party pins are unmeasured on 2.0, so the gap is not quantified). Sonnet-tier agents stay on the shipped Composer / Grok (correct under per-tier targeting, not a shortfall) unless you opt into `gpt-5.6-sol-high`. The orchestrators `/design` `/plan` `/debug` use the session model (set at launch), not the override table.
634
791
 
635
792
  ---
636
793
 
@@ -639,13 +796,18 @@ Cloud OpenAI-compatible cells tool-call-smoked (`tools:` round-trip `tool_calls`
639
796
  <!-- prettier-ignore -->
640
797
  | Host | Reads automatically | Format |
641
798
  | --- | --- | --- |
642
- | Claude Code | `CLAUDE.md` (root + nearest ancestor) | Plain markdown |
799
+ | Claude | `CLAUDE.md` (root + nearest ancestor) | Plain markdown |
643
800
  | Cursor | `AGENTS.md` (root, AGENTS.md spec) + `.cursor/rules/*.mdc` (MDC: markdown + optional YAML frontmatter with `description`, `globs`, `alwaysApply`) | Plain markdown / MDC |
644
- | Both (de-facto cross-host convention) | `AGENTS.md` increasingly read by all hosts incl. Claude Code, Codex, Cursor | Plain markdown |
801
+ | Both (de-facto cross-host convention) | `AGENTS.md` increasingly read by all hosts incl. Claude, Codex, Cursor | Plain markdown |
802
+
803
+ **Current setup:** `CLAUDE.md` and `.cursor/rules/bkit-rules.mdc` redirect to `.agents/rules.md`. `AGENTS.md` is the cross-host entry, read by every host. It holds the rules pointer, memory hygiene (memories hold pointers to docs, never copies) and the workflow gate:
645
804
 
646
- **Current setup:** `CLAUDE.md` + `.cursor/rules/bkit-rules.mdc` redirect to `.agents/rules.md`. `AGENTS.md` = cross-host dispatch spine (workflow router: tracker issue → label command dispatch), read by every host. **Host-scoped ownership:** `CLAUDE.md` ships `--claude` (Claude analog of `.cursor/rules/bkit-rules.mdc`, `--cursor`); `AGENTS.md` core (always). Each host brings redirect — no rule all three coexist. `--cursor`-only: no `CLAUDE.md`; `--claude`-only: no `.cursor/rules/`.
805
+ - **If** the prompt contains `bkit-{command}` → `.bkit/router.md` (command → each host's command file; bare `bkit-auto` → phase from the issue's labels).
806
+ - **Else** → normal work under `.agents/rules.md`.
647
807
 
648
- **Transform:** managed-block markers (`<!-- bkit:start -->` … `<!-- bkit:end -->`). Inside regenerated; outside preserved.
808
+ **Host-scoped ownership:** `CLAUDE.md` ships with `--claude` (the Claude analog of `.cursor/rules/bkit-rules.mdc`, which ships with `--cursor`). `AGENTS.md` ships with core (always). Each host brings its own redirect; there is no rule that all three coexist. `--cursor`-only: no `CLAUDE.md`. `--claude`-only: no `.cursor/rules/`.
809
+
810
+ **Transform:** managed-block markers (`<!-- bkit:start -->` … `<!-- bkit:end -->`). Inside is regenerated; outside is preserved.
649
811
 
650
812
  ---
651
813
 
@@ -654,10 +816,10 @@ Cloud OpenAI-compatible cells tool-call-smoked (`tools:` round-trip `tool_calls`
654
816
  <!-- prettier-ignore -->
655
817
  | Host | Mechanism | Location |
656
818
  | --- | --- | --- |
657
- | Claude Code | 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 |
819
+ | 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 |
658
820
  | Cursor | Cursor 2.4+ Agent Skills (similar shape). | `.cursor/skills/` (per docs); `.agents/skills/` referenced via custom routing |
659
821
 
660
- `.agents/skills/` = **canonical project skill directory**. Both hosts read. No per-host transform. List in `.agents/skills.md`.
822
+ `.agents/skills/` = **canonical project skill directory**. Both hosts read it. There is no per-host transform. Skills are listed in `.agents/skills.md`.
661
823
 
662
824
  ---
663
825
 
@@ -666,37 +828,61 @@ Cloud OpenAI-compatible cells tool-call-smoked (`tools:` round-trip `tool_calls`
666
828
  <!-- prettier-ignore -->
667
829
  | Host | Mechanism |
668
830
  | --- | --- |
669
- | Claude Code | Synchronous `Agent` tool calls; parallel calls in single turn = parallel execution within main agent. No first-class async/background concept. |
831
+ | Claude | Synchronous `Agent` tool calls; parallel calls in single turn = parallel execution within main agent. No first-class async / background concept. |
670
832
  | Cursor | `is_background: true` on subagent → spawns Cursor Cloud Agent that runs detached; main agent continues. Async by design. |
671
- | opencode | Concurrent `Task` dispatch (spike-proven: 3 distinct subagents run concurrently, wall-clock < serial sum). Real parallelism only when the backend serves requests concurrently — true for every provider (openrouter, ollama, opencode-zen, opencode-go). The workflow text is unchanged — concurrency is bounded at the Ollama server, not in the command files. |
833
+ | OpenCode | Concurrent `Task` dispatch (spike-proven: 3 distinct subagents run concurrently, wall-clock < serial sum). Real parallelism only when the backend serves requests concurrently — true for every provider (openrouter, ollama, OpenCode-zen, OpenCode-go). The workflow text is unchanged — concurrency is bounded at the Ollama server, not in the command files. |
834
+
835
+ **Implication:** parallel fan-outs (the triplet `bkit-design-brainstorm-ideate-1`/`-2`/`-3`; `bkit-plan-review-1`/`-2` + `bkit-plan-scope-check`; the pairs `bkit-design-review-*`, `bkit-build-challenge-*`) run per host:
836
+
837
+ - Claude: concurrent `Agent` calls in one turn.
838
+ - Cursor: opt-in `is_background: true` (default off; host config can flip it at install).
839
+ - OpenCode: concurrent `Task`, real on every provider.
840
+
841
+ ---
842
+
843
+ ## Long-running shell commands
844
+
845
+ A full test gate runs for minutes, and a gate that waits for the machine-wide tests lock runs for longer. What a host does with a shell command that outlives one tool call differs per host, so the time a bkit verb may spend waiting inside one call is a host property, not a repo property. `bkit tests run`, `bkit tests changed` and `bkit branches push` read it from `BKIT_LOCK_WAIT_S`.
846
+
847
+ <!-- prettier-ignore -->
848
+ | Host | One tool call | Past the call's limit | Told when it ends | `BKIT_LOCK_WAIT_S` |
849
+ | --- | --- | --- | --- | --- |
850
+ | Claude | `Bash`: two minutes by default; Claude may ask for up to ten (`BASH_DEFAULT_TIMEOUT_MS`, `BASH_MAX_TIMEOUT_MS`) | Moved to the background and kept running (off under `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1` and in bare mode); `run_in_background: true` starts it there. An unattended session (`-p`, Agent SDK, CI, cloud) stops a background command after 30 minutes by default and 2 hours at most; a local session never stops one | Yes: Claude is re-invoked when the command exits and reads its output file | `1200`, shipped in `.claude/settings.json` `env`: a 20-minute wait plus a 10-minute gate stays inside the unattended 30-minute cap |
851
+ | Codex | `exec_command` under unified exec (`features.unified_exec`, on by default) returns after its yield time while the process keeps running as a resumable session | The model reads on with `write_stdin` polls, each at most `background_terminal_max_timeout` (300000 ms by default); managed requirements can turn the resumable path off | No: the model polls | unset → 60 s, then exit 81 and a re-run |
852
+ | Antigravity | `run_command` returns after `WaitMsBeforeAsync` | Continues as a background task; `manage_task` (`list`, `kill`, `status`, `send_input`) polls it, and the Stop hook's `fullyIdle` stays `false` while one runs | No: the agent polls | unset → 60 s, then exit 81 and a re-run |
853
+ | 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
+ | 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
+
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.
672
857
 
673
- **Implication:** parallel fan-outs (triplet `bkit-design-brainstorm-ideate-1`/`-2`/`-3`; `bkit-plan-review-1`/`-2` + `bkit-plan-scope-check`; pairs `bkit-design-review-*`, `bkit-build-challenge-*`) — Claude: concurrent `Agent` in one turn; Cursor: opt-in `is_background: true` (default off; host config can flip at install); opencode: concurrent `Task` — real on every provider.
858
+ **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.
674
859
 
675
860
  ---
676
861
 
677
862
  ## Tool name parity
678
863
 
679
- Claude spelling in subagent `tools:` and command bodies (`Bash`, `Edit`, `Read`, etc.). Cursor uses different identifiers (`terminal`, `edit_file`, `read_file`, `apply_diff`). Claude names → Cursor `tools:` allowlist (alias vs strict) unverified. Mapping in `bkit/hosts/cursor.ts`.
864
+ Subagent `tools:` and command bodies use the Claude spelling (`Bash`, `Edit`, `Read`, etc.). Cursor uses different identifiers (`terminal`, `edit_file`, `read_file`, `apply_diff`). T3 (`applyT3`, `.bkit/core/engine/render/hosts.ts`) passes `tools:` through unchanged, with no name mapping. Cursor CLI 2026.10.01 does not enforce `tools:` (measured, § Architectural note — `readonly` reconciled), so the spelling has no effect there.
680
865
 
681
866
  ---
682
867
 
683
868
  ## How to add a new host
684
869
 
685
- 1. Add row to § Supported hosts above.
686
- 2. Document deltas per concern (subagent invocation, frontmatter, hooks, permissions, runtime, etc.).
687
- 3. Implement transforms in `bkit/hosts/<name>.ts`. Each delta = one transform rule.
688
- 4. Drop static templates in `bkit/templates/<name>/` (settings, hooks, runtime).
689
- 5. Regression test: fresh-repo install; verify 5 phase commands + 7 worktree utilities E2E.
690
- 6. Update `AGENTS.md` routing table with new host command paths.
870
+ 1. Add a row to § Supported hosts above.
871
+ 2. Document the deltas per concern (subagent invocation, frontmatter, hooks, permissions, runtime, etc.).
872
+ 3. Implement the transforms in `.bkit/core/engine/render/hosts.ts`. Each delta = one transform rule.
873
+ 4. Add the host's install module (`.bkit/core/engine/install/modules/`), its manifest entries (`.bkit/core/engine/install/manifest.ts`), the hooks and host config listed in § Supported hosts, and parity-test cases.
874
+ 5. Regression test: a fresh-repo install. Verify the 5 phase commands and the 7 worktree utilities E2E.
875
+ 6. Update the `AGENTS.md` routing table with the new host's command paths.
691
876
 
692
877
  ---
693
878
 
694
879
  ## Verify against current Cursor surface
695
880
 
696
- Cursor API/frontmatter churn — confirm before dependent changes:
881
+ The Cursor API and frontmatter churn. Confirm these before any change that depends on them:
697
882
 
698
- - Cursor model IDs in § Cursor model catalog still exist, not superseded.
699
- - Cursor `readonly: true` semantics — file writes only, or bash/terminal too.
883
+ - Cursor model IDs in § Cursor model catalog still exist, and are not superseded.
884
+ - Cursor `readonly: true` semantics: file writes only, or bash / terminal too.
700
885
  - Cursor tool-name parity (`Bash` vs `terminal`, `Edit` vs `edit_file`, etc.).
701
886
  - Cursor `Task` resolution: `/<name>` → `.cursor/agents/<name>.md` (mirrors Claude `Agent` `@<name>` → `.claude/agents/<name>.md`).
702
- - `AGENTS.md` adoption — when all hosts read natively, redirects (`CLAUDE.md`, `.cursor/rules/bkit-rules.mdc`) can shrink.
887
+ - Cursor agent terminal: whether a command past the call's limit is stopped, moved to the background or reported on exit (§ Long-running shell commands: undocumented today).
888
+ - `AGENTS.md` adoption: when all hosts read it natively, the redirects (`CLAUDE.md`, `.cursor/rules/bkit-rules.mdc`) can shrink.