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