@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.
- package/.bkit/README.md +154 -151
- package/.bkit/core/.agents/context.md +95 -29
- package/.bkit/core/.agents/docs.md +17 -15
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-gateguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-guardrails.cjs +6 -5
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-readguard.cjs +1 -0
- package/.bkit/core/.agents/plugins/bkit/hooks/bkit-rules.cjs +65 -0
- package/.bkit/core/.agents/rules.md +108 -107
- package/.bkit/core/.agents/skills.md +63 -15
- package/.bkit/core/.bkit/README.md +154 -151
- package/.bkit/core/.bkit/authoring.md +714 -84
- package/.bkit/core/.bkit/cli.md +407 -0
- package/.bkit/core/.bkit/cloud.md +281 -193
- package/.bkit/core/.bkit/comparison.md +43 -41
- package/.bkit/core/.bkit/install.md +154 -84
- package/.bkit/core/.bkit/jsonl.md +193 -130
- package/.bkit/core/.bkit/pipeline.md +114 -114
- package/.bkit/core/.bkit/prompts.md +272 -165
- package/.bkit/core/.bkit/providers.md +457 -271
- package/.bkit/core/.bkit/router.md +69 -0
- package/.bkit/core/.bkit/templates.md +529 -256
- package/.bkit/core/.bkit/trackers.md +80 -52
- package/.bkit/core/.bkit/workflows.md +589 -504
- package/.bkit/core/.claude/hooks/bkit-gateguard.cjs +2 -2
- package/.bkit/core/.claude/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.claude/hooks/bkit-preflight.sh +45 -14
- package/.bkit/core/.codex/hooks/bkit-guardrails.cjs +3 -3
- package/.bkit/core/.codex/hooks/bkit-rules.cjs +57 -0
- package/.bkit/core/.cursor/hooks/bkit-guardrails.cjs +7 -7
- package/.bkit/core/.cursor/hooks/bkit-preflight.sh +47 -12
- package/.bkit/core/.opencode/plugin/bkit-rules.js +89 -0
- package/.bkit/core/AGENTS.md +5 -73
- package/.bkit/core/docs/templates/bkit-audit-accessibility.md +127 -105
- package/.bkit/core/docs/templates/bkit-audit-adoption.md +104 -70
- package/.bkit/core/docs/templates/bkit-audit-agents.md +94 -72
- package/.bkit/core/docs/templates/bkit-audit-aio-seo.md +99 -78
- package/.bkit/core/docs/templates/bkit-audit-analytics.md +140 -82
- package/.bkit/core/docs/templates/bkit-audit-annotations.md +98 -72
- package/.bkit/core/docs/templates/bkit-audit-app-performance.md +121 -96
- package/.bkit/core/docs/templates/bkit-audit-app-store.md +157 -76
- package/.bkit/core/docs/templates/bkit-audit-architecture.md +113 -71
- package/.bkit/core/docs/templates/bkit-audit-ci-performance.md +75 -72
- package/.bkit/core/docs/templates/bkit-audit-config.md +122 -76
- package/.bkit/core/docs/templates/bkit-audit-cost.md +85 -74
- package/.bkit/core/docs/templates/bkit-audit-coverage.md +75 -68
- package/.bkit/core/docs/templates/bkit-audit-database.md +101 -70
- package/.bkit/core/docs/templates/bkit-audit-dead-code.md +164 -83
- package/.bkit/core/docs/templates/bkit-audit-deferrals.md +115 -86
- package/.bkit/core/docs/templates/bkit-audit-dependencies.md +264 -88
- package/.bkit/core/docs/templates/bkit-audit-documentation.md +118 -93
- package/.bkit/core/docs/templates/bkit-audit-duplication.md +139 -86
- package/.bkit/core/docs/templates/bkit-audit-failures.md +110 -81
- package/.bkit/core/docs/templates/bkit-audit-flakes.md +99 -74
- package/.bkit/core/docs/templates/bkit-audit-gates.md +105 -77
- package/.bkit/core/docs/templates/bkit-audit-issues.md +104 -80
- package/.bkit/core/docs/templates/bkit-audit-llm.md +131 -58
- package/.bkit/core/docs/templates/bkit-audit-logs.md +123 -100
- package/.bkit/core/docs/templates/bkit-audit-models.md +98 -53
- package/.bkit/core/docs/templates/bkit-audit-privacy.md +56 -52
- package/.bkit/core/docs/templates/bkit-audit-prompts.md +63 -54
- package/.bkit/core/docs/templates/bkit-audit-red-team.md +124 -68
- package/.bkit/core/docs/templates/bkit-audit-reliability.md +95 -70
- package/.bkit/core/docs/templates/bkit-audit-repo.md +169 -73
- package/.bkit/core/docs/templates/bkit-audit-security.md +206 -96
- package/.bkit/core/docs/templates/bkit-audit-slop.md +77 -70
- package/.bkit/core/docs/templates/bkit-audit-testing.md +162 -114
- package/.bkit/core/docs/templates/bkit-audit-usability.md +113 -71
- package/.bkit/core/docs/templates/bkit-plan.md +138 -132
- package/.bkit/core/engine/checks/after/auth.ts +40 -37
- package/.bkit/core/engine/checks/after/ci-yml.ts +65 -2
- package/.bkit/core/engine/checks/after/index.ts +12 -2
- package/.bkit/core/engine/checks/after/tools.ts +80 -33
- package/.bkit/core/engine/checks/before/context-fetch.ts +227 -33
- package/.bkit/core/engine/checks/before/env.ts +1 -1
- package/.bkit/core/engine/checks/before/index.ts +7 -0
- package/.bkit/core/engine/checks/before/repo.ts +40 -0
- package/.bkit/core/engine/checks/status-holes.ts +916 -123
- package/.bkit/core/engine/checks/tips/catalogue.ts +68 -17
- package/.bkit/core/engine/checks/tips/detect.ts +32 -0
- package/.bkit/core/engine/checks/tips/index.ts +47 -6
- package/.bkit/core/engine/cli.ts +238 -84
- package/.bkit/core/engine/commands/analysis.ts +128 -76
- package/.bkit/core/engine/commands/ci/ci.ts +363 -29
- package/.bkit/core/engine/commands/ci/pins.ts +172 -0
- package/.bkit/core/engine/commands/ci/push-gate.ts +223 -0
- package/.bkit/core/engine/commands/install/uninstall.ts +21 -27
- package/.bkit/core/engine/commands/install/upgrade.ts +32 -15
- package/.bkit/core/engine/commands/land.ts +126 -11
- package/.bkit/core/engine/commands/lib.ts +303 -6
- package/.bkit/core/engine/commands/registry.ts +6 -2
- package/.bkit/core/engine/commands/setup/setup.ts +1 -0
- package/.bkit/core/engine/commands/stats.ts +91 -35
- package/.bkit/core/engine/commands/workflow/branches.ts +1477 -117
- package/.bkit/core/engine/commands/workflow/challenge.ts +114 -39
- package/.bkit/core/engine/commands/workflow/completeness.ts +109 -0
- package/.bkit/core/engine/commands/workflow/context.ts +433 -55
- package/.bkit/core/engine/commands/workflow/counters.ts +244 -39
- package/.bkit/core/engine/commands/workflow/decisions.ts +61 -17
- package/.bkit/core/engine/commands/workflow/disk.ts +237 -55
- package/.bkit/core/engine/commands/workflow/fids.ts +19 -1
- package/.bkit/core/engine/commands/workflow/issues.ts +6 -0
- package/.bkit/core/engine/commands/workflow/ledgers.ts +458 -18
- package/.bkit/core/engine/commands/workflow/locks.ts +2 -0
- package/.bkit/core/engine/commands/workflow/plan-blocks.ts +124 -15
- package/.bkit/core/engine/commands/workflow/plans.ts +257 -0
- package/.bkit/core/engine/commands/workflow/prs.ts +12 -3
- package/.bkit/core/engine/commands/workflow/repo.ts +8 -0
- package/.bkit/core/engine/commands/workflow/roadmap.ts +56 -15
- package/.bkit/core/engine/commands/workflow/run-facts.ts +22 -31
- package/.bkit/core/engine/commands/workflow/runs.ts +652 -34
- package/.bkit/core/engine/commands/workflow/runtime.ts +3 -0
- package/.bkit/core/engine/commands/workflow/skills.ts +1 -0
- package/.bkit/core/engine/commands/workflow/status.ts +200 -17
- package/.bkit/core/engine/commands/workflow/step-table.ts +75 -33
- package/.bkit/core/engine/commands/workflow/steps.ts +635 -24
- package/.bkit/core/engine/commands/workflow/summary-findings.ts +177 -0
- package/.bkit/core/engine/commands/workflow/summary.ts +192 -46
- package/.bkit/core/engine/commands/workflow/tasks.ts +409 -0
- package/.bkit/core/engine/commands/workflow/test-blocks.ts +254 -0
- package/.bkit/core/engine/commands/workflow/tests-changed.ts +201 -0
- package/.bkit/core/engine/commands/workflow/tests.ts +1285 -356
- package/.bkit/core/engine/commands/workflow/workflows.ts +228 -43
- package/.bkit/core/engine/commands/workflow/worktrees.ts +389 -47
- package/.bkit/core/engine/install/cloud-env.ts +251 -121
- package/.bkit/core/engine/install/context-ci-workflow.ts +102 -0
- package/.bkit/core/engine/install/manifest.ts +60 -12
- package/.bkit/core/engine/install/modules/antigravity.ts +3 -2
- package/.bkit/core/engine/install/modules/cloud.ts +3 -3
- package/.bkit/core/engine/install/modules/codex.ts +15 -2
- package/.bkit/core/engine/install/modules/core.ts +956 -52
- package/.bkit/core/engine/install/modules/cursor.ts +6 -6
- package/.bkit/core/engine/install/modules/opencode.ts +16 -4
- package/.bkit/core/engine/install/template-notes.ts +130 -0
- package/.bkit/core/engine/install/version-file.ts +3 -2
- package/.bkit/core/engine/install/write.ts +5 -0
- package/.bkit/core/engine/ledgers/compact.ts +124 -0
- package/.bkit/core/engine/ledgers/journal.ts +291 -0
- package/.bkit/core/engine/ledgers/status.ts +160 -9
- package/.bkit/core/engine/ledgers/telemetry.ts +158 -21
- package/.bkit/core/engine/render/hosts.ts +114 -14
- package/.bkit/core/engine/shared/bkit-latest.ts +26 -4
- package/.bkit/core/engine/shared/dep-updater.ts +60 -0
- package/.bkit/core/engine/shared/egress.ts +1 -1
- package/.bkit/core/engine/shared/package-manager.ts +9 -0
- package/.bkit/core/engine/shared/settings.ts +92 -17
- package/.bkit/core/engine/shared/timeouts.ts +2 -0
- package/.bkit/core/engine/tools/cli-doc.ts +111 -0
- package/.bkit/core/engine/tools/grammar-density.ts +1 -1
- package/.bkit/core/engine/tools/instructions-sources.ts +15 -17
- package/.bkit/core/engine/tools/instructions.ts +94 -43
- package/.bkit/core/hooks/antigravity-hook.js +25 -10
- package/.bkit/core/hooks/gateguard-engine.js +53 -29
- package/.bkit/core/hooks/guardrails-shell.js +4 -4
- package/.bkit/core/hooks/guardrails-tiers.js +3 -3
- package/.bkit/core/hooks/preflight-linear.sh +9 -9
- package/.bkit/core/hooks/preflight-rules.sh +8 -0
- package/.bkit/core/hooks/readguard-engine.js +29 -10
- package/.bkit/core/hooks/session-rules-advisory.js +61 -0
- package/.bkit/core/prompts/bkit-audit-generate.md +187 -116
- package/.bkit/core/prompts/bkit-build-challenge-1.md +56 -37
- package/.bkit/core/prompts/bkit-build-challenge-2.md +65 -45
- package/.bkit/core/prompts/bkit-build-install-skills.md +38 -29
- package/.bkit/core/prompts/bkit-build-plan-convert.md +43 -32
- package/.bkit/core/prompts/bkit-build-plan-current.md +49 -39
- package/.bkit/core/prompts/bkit-build-plan-gaps-remediate.md +79 -55
- package/.bkit/core/prompts/bkit-build-plan-tasks.md +149 -0
- package/.bkit/core/prompts/bkit-build-plan-tests.md +120 -0
- package/.bkit/core/prompts/bkit-build-plan-verify.md +87 -50
- package/.bkit/core/prompts/bkit-debug-abort-handover.md +36 -35
- package/.bkit/core/prompts/bkit-debug-failure-diagnose.md +96 -64
- package/.bkit/core/prompts/bkit-debug-failure-remediate.md +54 -45
- package/.bkit/core/prompts/bkit-debug-failure-reproduce.md +42 -33
- package/.bkit/core/prompts/bkit-debug-failure-soak.md +53 -37
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-1.md +35 -30
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-2.md +34 -29
- package/.bkit/core/prompts/bkit-design-brainstorm-ideate-3.md +32 -28
- package/.bkit/core/prompts/bkit-design-generate.md +68 -52
- package/.bkit/core/prompts/bkit-design-organise.md +73 -35
- package/.bkit/core/prompts/bkit-design-review-1.md +58 -54
- package/.bkit/core/prompts/bkit-design-review-2.md +54 -50
- package/.bkit/core/prompts/bkit-design-spike.md +54 -47
- package/.bkit/core/prompts/bkit-design-update.md +42 -31
- package/.bkit/core/prompts/bkit-plan-generate.md +76 -58
- package/.bkit/core/prompts/bkit-plan-review-1.md +63 -49
- package/.bkit/core/prompts/bkit-plan-review-2.md +60 -48
- package/.bkit/core/prompts/bkit-plan-scope-check.md +53 -46
- package/.bkit/core/prompts/bkit-plan-update.md +70 -52
- package/.bkit/core/prompts/bkit-ship-conflict-resolve.md +82 -50
- package/.bkit/core/prompts/bkit-ship-deferred-sweep.md +80 -45
- package/.bkit/core/prompts/bkit-ship-update-docs.md +35 -29
- package/.bkit/core/prompts/bkit-utility-compress-markdown.md +55 -49
- package/.bkit/core/prompts/bkit-utility-update-decisions.md +76 -49
- package/.bkit/core/prompts/bkit-utility-update-deferrals.md +70 -41
- package/.bkit/core/prompts/bkit-utility-update-documentation.md +33 -30
- package/.bkit/core/prompts/bkit-utility-update-failures.md +73 -43
- package/.bkit/core/prompts/bkit-utility-update-knowledge.md +77 -50
- package/.bkit/core/prompts/bkit-utility-update-roadmap.md +77 -45
- package/.bkit/core/prompts/bkit-utility-update-tracker.md +144 -68
- package/.bkit/core/workflows/bkit-auto.md +53 -30
- package/.bkit/core/workflows/bkit-build.md +635 -304
- package/.bkit/core/workflows/bkit-debug.md +301 -148
- package/.bkit/core/workflows/bkit-design.md +167 -95
- package/.bkit/core/workflows/bkit-plan.md +172 -84
- package/.bkit/core/workflows/bkit-ship.md +299 -152
- package/.bkit/shared/.agents/plugins/bkit/hooks.json +10 -0
- package/.bkit/shared/.claude/bkit-cloud.md +12 -10
- package/.bkit/shared/.claude/settings.json +3 -0
- package/.bkit/shared/.codex/bkit-cloud.md +98 -0
- package/.bkit/shared/.codex/hooks.json +20 -0
- package/.bkit/shared/.cursor/bkit-cloud.md +3 -3
- package/.bkit/shared/.opencode/opencode.json +1 -1
- package/.bkit/shared/CLAUDE.md +5 -1
- package/.bkit/shared/GEMINI.md +4 -1
- package/.bkit/shared/docs/architecture.md +4 -7
- package/.bkit/shared/docs/data-schema.md +4 -7
- package/.bkit/shared/docs/deployments.md +239 -166
- package/.bkit/shared/docs/design.md +11 -12
- package/.bkit/shared/docs/noise.md +8 -7
- package/.bkit/shared/docs/observability.md +5 -8
- package/.bkit/shared/docs/security.md +35 -17
- package/.bkit/shared/docs/setup.md +29 -18
- package/.bkit/shared/docs/technology.md +3 -6
- package/.bkit/shared/docs/testing.md +282 -176
- package/.bkit/shared/gitignore +6 -2
- package/.bkit/templates/.claude/hooks/bkit-cloud-bootstrap.sh +15 -16
- package/.bkit/templates/.cursor/Dockerfile +12 -8
- package/.bkit/templates/.cursor/environment.json +1 -1
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-bug.yml +10 -8
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-change.yml +24 -12
- package/.bkit/templates/.github/ISSUE_TEMPLATE/bkit-idea.yml +3 -3
- package/.bkit/templates/.github/renovate.json5 +34 -6
- package/.bkit/templates/.github/workflows/bkit-ci.yml +53 -50
- package/.bkit/templates/.github/workflows/bkit-cloud.yml +13 -14
- package/.bkit/templates/.github/workflows/bkit-health.yml +97 -0
- package/.bkit/templates/.github/workflows/bkit-renovate.yml +5 -4
- package/.bkit/templates/.github/workflows/bkit-trivy.yml +5 -4
- package/.bkit/templates/.husky/pre-commit +2 -2
- package/.bkit/templates/.husky/pre-push +95 -35
- package/.bkit/templates/.prettierignore +6 -7
- package/.bkit/templates/.vale.ini +27 -27
- package/.bkit/templates/context/bkit-cloudrun.md +23 -15
- package/.bkit/templates/context/bkit-expo.md +70 -52
- package/.bkit/templates/context/bkit-github.md +93 -56
- package/.bkit/templates/context/bkit-inngest.md +21 -15
- package/.bkit/templates/context/bkit-maestro.md +22 -16
- package/.bkit/templates/context/bkit-playwright.md +23 -17
- package/.bkit/templates/context/bkit-resend.md +12 -10
- package/.bkit/templates/context/bkit-sentry.md +30 -20
- package/.bkit/templates/context/bkit-serena.md +8 -7
- package/.bkit/templates/context/bkit-stripe.md +14 -13
- package/.bkit/templates/context/bkit-supabase.md +16 -13
- package/.bkit/templates/context/bkit-tavily.md +14 -11
- package/.bkit/templates/context/bkit-vercel.md +27 -18
- package/.bkit/templates/docs/capabilities.md +15 -14
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.mjs → bkit-check-accepted-divergences.mjs} +6 -3
- package/.bkit/templates/scripts/ci/{check-accepted-divergences.test.mjs → bkit-check-accepted-divergences.test.mjs} +3 -3
- package/.bkit/templates/scripts/ci/{check-capstone.mjs → bkit-check-capstone.mjs} +2 -2
- package/.bkit/templates/scripts/ci/{check-capstone.test.mjs → bkit-check-capstone.test.mjs} +4 -4
- package/.bkit/templates/scripts/ci/{check-dependency-audit.mjs → bkit-check-dependency-audit.mjs} +103 -18
- package/.bkit/templates/scripts/ci/{check-dependency-audit.test.mjs → bkit-check-dependency-audit.test.mjs} +31 -3
- package/.bkit/templates/scripts/ci/bkit-machine-lock.sh +387 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.mjs +75 -0
- package/.bkit/templates/scripts/ci/bkit-test-awake.test.mjs +160 -0
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.mjs → bkit-resolve-push-base.mjs} +3 -3
- package/.bkit/templates/scripts/ci/lanes/{resolve-push-base.test.mjs → bkit-resolve-push-base.test.mjs} +4 -4
- package/.bkit/templates/scripts/cleanup/bkit-disk-prune.mjs +9 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-drift.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graph-eager.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-embed.py +63 -0
- package/.bkit/templates/scripts/graphify/bkit-graph-imports.py +2 -2
- package/.bkit/templates/scripts/graphify/bkit-graph-pre-push.sh +69 -18
- package/.bkit/templates/scripts/graphify/bkit-graph-repair.py +3 -3
- package/.bkit/templates/scripts/graphify/bkit-graph-surface.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-graphml.py +1 -1
- package/.bkit/templates/scripts/graphify/bkit-graphify-rollup.py +197 -126
- package/.bkit/templates/scripts/graphify/bkit-graphify.sh +64 -41
- package/.bkit/templates/scripts/slop/bkit-slop-type-suppression.mjs +23 -7
- package/.bkit/templates/slop-scan.config.json +9 -2
- package/CHANGELOG.md +119 -0
- package/README.md +250 -76
- package/dist/checks/after/auth.js +36 -33
- package/dist/checks/after/ci-yml.js +52 -2
- package/dist/checks/after/index.js +12 -4
- package/dist/checks/after/tools.js +73 -33
- package/dist/checks/before/context-fetch.js +218 -33
- package/dist/checks/before/env.js +1 -1
- package/dist/checks/before/index.js +6 -2
- package/dist/checks/before/repo.js +35 -1
- package/dist/checks/status-holes.js +739 -114
- package/dist/checks/tips/catalogue.js +59 -17
- package/dist/checks/tips/detect.js +30 -0
- package/dist/checks/tips/index.js +48 -6
- package/dist/cli.js +222 -84
- package/dist/commands/analysis.js +77 -53
- package/dist/commands/ci/ci.js +302 -25
- package/dist/commands/ci/pins.js +142 -0
- package/dist/commands/ci/push-gate.js +194 -0
- package/dist/commands/install/uninstall.js +23 -27
- package/dist/commands/install/upgrade.js +21 -11
- package/dist/commands/land.js +126 -10
- package/dist/commands/lib.js +244 -5
- package/dist/commands/registry.js +6 -2
- package/dist/commands/setup/setup.js +1 -0
- package/dist/commands/stats.js +69 -30
- package/dist/commands/workflow/branches.js +1232 -111
- package/dist/commands/workflow/challenge.js +90 -37
- package/dist/commands/workflow/completeness.js +97 -0
- package/dist/commands/workflow/context.js +371 -51
- package/dist/commands/workflow/counters.js +206 -40
- package/dist/commands/workflow/decisions.js +60 -17
- package/dist/commands/workflow/disk.js +213 -55
- package/dist/commands/workflow/fids.js +18 -1
- package/dist/commands/workflow/issues.js +6 -0
- package/dist/commands/workflow/ledgers.js +372 -21
- package/dist/commands/workflow/locks.js +2 -0
- package/dist/commands/workflow/plan-blocks.js +78 -14
- package/dist/commands/workflow/plans.js +205 -0
- package/dist/commands/workflow/prs.js +12 -3
- package/dist/commands/workflow/repo.js +6 -0
- package/dist/commands/workflow/roadmap.js +50 -17
- package/dist/commands/workflow/run-facts.js +23 -28
- package/dist/commands/workflow/runs.js +530 -33
- package/dist/commands/workflow/runtime.js +3 -0
- package/dist/commands/workflow/skills.js +1 -0
- package/dist/commands/workflow/status.js +166 -19
- package/dist/commands/workflow/step-table.js +61 -29
- package/dist/commands/workflow/steps.js +542 -26
- package/dist/commands/workflow/summary-findings.js +117 -0
- package/dist/commands/workflow/summary.js +154 -41
- package/dist/commands/workflow/tasks.js +378 -0
- package/dist/commands/workflow/test-blocks.js +231 -0
- package/dist/commands/workflow/tests-changed.js +172 -0
- package/dist/commands/workflow/tests.js +1013 -321
- package/dist/commands/workflow/workflows.js +191 -38
- package/dist/commands/workflow/worktrees.js +310 -42
- package/dist/install/cloud-env.js +233 -99
- package/dist/install/context-ci-workflow.js +85 -0
- package/dist/install/manifest.js +57 -12
- package/dist/install/modules/antigravity.js +3 -2
- package/dist/install/modules/cloud.js +3 -3
- package/dist/install/modules/codex.js +12 -2
- package/dist/install/modules/core.js +851 -53
- package/dist/install/modules/cursor.js +6 -6
- package/dist/install/modules/opencode.js +11 -5
- package/dist/install/template-notes.js +116 -0
- package/dist/install/version-file.js +3 -2
- package/dist/ledgers/compact.js +87 -0
- package/dist/ledgers/journal.js +233 -0
- package/dist/ledgers/status.js +115 -5
- package/dist/ledgers/telemetry.js +121 -17
- package/dist/render/hosts.js +100 -14
- package/dist/shared/bkit-latest.js +26 -4
- package/dist/shared/dep-updater.js +49 -0
- package/dist/shared/egress.js +1 -1
- package/dist/shared/package-manager.js +6 -0
- package/dist/shared/settings.js +59 -10
- package/dist/shared/timeouts.js +2 -0
- package/dist/tools/cli-doc.js +97 -0
- package/dist/tools/grammar-density.js +1 -1
- package/dist/tools/instructions-sources.js +15 -16
- package/dist/tools/instructions.js +83 -39
- package/package.json +58 -42
- package/.bkit/core/.bkit/lite.md +0 -73
- package/.bkit/core/engine/commands/workflow/workstreams.ts +0 -172
- package/.bkit/core/prompts/bkit-build-plan-execute.md +0 -124
- package/.bkit/templates/scripts/ci/bkit-local-stack-lock.sh +0 -194
- package/dist/commands/workflow/workstreams.js +0 -149
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Filler.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Hedging.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/LLMSlop.yml +0 -0
- /package/.bkit/templates/.vale/styles/{House → Bkit}/Verbose.yml +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-advisories.json → bkit-accepted-advisories.json} +0 -0
- /package/.bkit/templates/scripts/ci/{accepted-divergences.json → bkit-accepted-divergences.json} +0 -0
- /package/.bkit/templates/scripts/launchd/{launchd.env.example → bkit-launchd.env.example} +0 -0
- /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:**
|
|
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
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
> -
|
|
13
|
-
> -
|
|
14
|
-
> -
|
|
15
|
-
> -
|
|
16
|
-
> -
|
|
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
|
|
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
|
-
|
|
|
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.** **
|
|
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
|
-
**
|
|
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
|
|
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
|
-
|
|
|
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
|
-
|
|
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 =
|
|
51
|
-
| `tools:` not enforced | No per-agent tool allowlist upstream
|
|
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
|
|
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
|
|
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
|
-
###
|
|
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
|
|
63
|
-
| Workflows =
|
|
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`).
|
|
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
|
|
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
|
|
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 (
|
|
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
|
|
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
|
-
|
|
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
|
|
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 (
|
|
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.
|
|
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.**
|
|
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
|
|
98
|
-
- **
|
|
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`
|
|
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
|
|
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
|
-
|
|
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-
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
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
|
|
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,
|
|
131
|
-
- Subagent body files
|
|
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 |
|
|
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) |
|
|
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).
|
|
146
|
-
| `permissionMode` | required (`acceptEdits` standard) | not supported | not supported | Drop on Cursor and
|
|
147
|
-
| `maxTurns` | required | not supported | not supported | Drop on Cursor and
|
|
148
|
-
| `autoCompactWindow` | `300000` on every `bkit-*` agent | not supported | not supported | Drop on
|
|
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.
|
|
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 |
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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.**
|
|
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`** ($) —
|
|
175
|
-
- **`cursor-grok-4.5-high`** ($$) —
|
|
176
|
-
- **`claude-opus-5-thinking-high`** ($$$) —
|
|
177
|
-
- **`claude-sonnet-5-thinking-high`/`-xhigh`** ($$$) —
|
|
178
|
-
- **`gpt-5.*`** ($$$) —
|
|
179
|
-
- **`claude-fable-5-thinking-high`/`-xhigh`** ($$$$) —
|
|
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:"
|
|
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.**
|
|
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`.**
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
205
|
+
These are the IDs that Cursor uses to route by dashboard label.
|
|
201
206
|
|
|
202
|
-
> **Stale-risk:** dashboard label-routing 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
|
|
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
|
|
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:**
|
|
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
|
|
229
|
-
- Keep `readonly: true
|
|
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 |
|
|
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).
|
|
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
|
|
248
|
-
-
|
|
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
|
|
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
|
|
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 /
|
|
264
|
-
| Secret files | Read tool; shell reads on
|
|
265
|
-
| Network | `curl` / `wget`, fetch tool | ask unless host
|
|
266
|
-
| Shell-as-edit-channel | `sed -i`, redirect into a source file | Advisory: edit skips pre-edit gates | All hosts except
|
|
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
|
|
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 |
|
|
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
|
|
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,
|
|
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,
|
|
297
|
-
| `readguard-payload.js` | Claude,
|
|
298
|
-
| `antigravity-hook.js` |
|
|
299
|
-
| `guardrails-shell.js` | Claude,
|
|
300
|
-
| `guardrails-tiers.js` |
|
|
301
|
-
| `guardrails-read.js` |
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
314
|
-
|
|
|
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-
|
|
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
|
-
**
|
|
380
|
+
**Subagents:** not exempt on any host. Dedup is per (session, agent, file) wherever the host names the agent.
|
|
321
381
|
|
|
322
|
-
|
|
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
|
-
|
|
388
|
+
On Codex and Cursor a subagent editing a file its parent already touched gets no checklist.
|
|
325
389
|
|
|
326
|
-
**Deny mode, per host:**
|
|
390
|
+
**Deny mode, per host:**
|
|
327
391
|
|
|
328
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
|
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
|
-
**
|
|
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 |
|
|
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` | `.
|
|
353
|
-
| File / secrets — shell (`cat .bkit/.env`) |
|
|
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`
|
|
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
|
|
356
|
-
| Granularity | Per-tool glob | Hook script (project-scoped, fail-open;
|
|
357
|
-
| Modes | `defaultMode: default \| acceptEdits \| plan \| bypassPermissions` |
|
|
358
|
-
| MCP server config | `.mcp.json` at repo root (`mcpServers.<name>.url`) | `.cursor/mcp.json` (same `mcpServers.<name>.url` shape) | `.opencode/opencode.json` → `mcp` |
|
|
359
|
-
| MCP tool approval | `permissions.allow` `mcp__<s>__*` from consumer `mcp-servers` (§ MCP servers) | Generated `.cursor/cli.json` `Mcp(<s>:*)` | `permission` `"<s>_*": "allow"` |
|
|
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` |
|
|
361
|
-
|
|
362
|
-
**Install behaviour:** template drops, host-specific encoding of the
|
|
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 -->`
|
|
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
|
-
|
|
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
|
|
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
|
|
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 -->`
|
|
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"` —
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
422
|
-
| Codex
|
|
423
|
-
|
|
|
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
|
-
|
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
>
|
|
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
|
|
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 —
|
|
480
|
-
|
|
481
|
-
**Install behaviour:** template drops
|
|
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
|
-
##
|
|
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-
|
|
496
|
-
| OpenRouter | `curl https://openrouter.ai/api/v1/models` |
|
|
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 (
|
|
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:**
|
|
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 `
|
|
505
|
-
2. Parse column
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
518
|
-
|
|
519
|
-
|
|
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
|
|
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
|
|
526
|
-
2. Pull every source
|
|
527
|
-
3.
|
|
528
|
-
4. Shortlist 1-2
|
|
529
|
-
5. Apply
|
|
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
|
|
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
|
|
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 |
|
|
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
|
-
|
|
652
|
+
**Four column classes — each answers a different question.**
|
|
552
653
|
|
|
553
|
-
|
|
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
|
-
|
|
664
|
+
### Budget band — the gap between subscription resets
|
|
556
665
|
|
|
557
|
-
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
|
679
|
+
| Cache-read ceiling (per Mtok) | Normal day | 2-day gap | Models that survive |
|
|
569
680
|
| --- | --- | --- | --- |
|
|
570
|
-
|
|
|
571
|
-
| `
|
|
572
|
-
| `
|
|
573
|
-
| `
|
|
574
|
-
| `
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
|
588
|
-
|
|
|
589
|
-
| `
|
|
590
|
-
| `
|
|
591
|
-
| `
|
|
592
|
-
| `
|
|
593
|
-
| `
|
|
594
|
-
| `
|
|
595
|
-
| `
|
|
596
|
-
| `
|
|
597
|
-
| `
|
|
598
|
-
| `
|
|
599
|
-
| `
|
|
600
|
-
|
|
601
|
-
|
|
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.
|
|
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
|
|
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`
|
|
611
|
-
| `openrouter` | `deepseek/deepseek-v4.1-flash`
|
|
612
|
-
| `cursor` | `cursor-grok-4.5-high`
|
|
613
|
-
| `ollama` (cloud) | `deepseek-v4.1-flash`
|
|
614
|
-
| `opencode-zen` | `opencode/deepseek-v4.1-flash`
|
|
615
|
-
| `opencode-go` | `opencode-go/deepseek-v4.1-flash`
|
|
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)
|
|
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
|
|
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
|
-
|
|
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)
|
|
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-
|
|
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
|
|
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`)
|
|
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
|
|
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
|
|
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
|
-
**
|
|
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
|
-
**
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
|
688
|
-
4.
|
|
689
|
-
5. Regression test: fresh-repo install
|
|
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
|
|
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
|
|
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
|
-
-
|
|
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.
|