feat(0.22.0): project pin + firewall flags (FIIA P0-4)

[ottomansky]

Summary

Closes FIIA P0-4 (project pin + firewall flags). Two orthogonal but complementary additions:

1. Explicit project-pin UX. The default_project field already lived on AppConfig and was auto-populated on first project add — but there was no CLI verb to change it, no env override, and no introspection. This PR adds kbagent project use <alias>, kbagent project current, and a KBAGENT_PROJECT env override, with a clean precedence rule for write-ops: --project > KBAGENT_PROJECT > pin > sole-project > fail-hard.
2. Session-only firewall sugar. Top-level --deny-writes / --deny-destructive flags synthesize a PermissionPolicy for the current invocation only and merge with any persisted policy. Never written to config.json — callers can safely run one-off blocked-mode commands without mutating their saved policy.

Version bumped to 0.22.0.

Behavior

Command / flag	Behavior
kbagent project use <alias>	Writes default_project = "<alias>" to config.json. Fails with CONFIG_ERROR / exit 5 if the alias isn't registered. Registered as write in the permission engine.
kbagent project current	Prints effective alias + source (env / pin / none). Reports BOTH the env override and the pinned value so misconfigurations are visible. Registered as read.
KBAGENT_PROJECT=<alias>	Overrides the pin for the current shell; loses to explicit --project. Empty string treated as unset (Unix convention).
--deny-writes	Session firewall: blocks cli:write + tool:write (spans write+destructive+admin). Exit 6 on blocked op.
--deny-destructive	Session firewall: blocks cli:destructive + tool:destructive (narrower — destructive only). Pure-write ops (e.g. storage create-bucket) stay allowed.
Stale pin (alias deleted out-of-band)	Now surfaces a repair-friendly CONFIG_ERROR ("run 'kbagent project use ' to repair") instead of silently fanning out.

Architecture

• ProjectService.use_project(alias) / current_project() / resolve_pinned_alias() — new business logic in the service layer.
• commands._helpers.resolve_project_alias() — thin CLI adapter that calls the service and converts ConfigError → exit 5. Public contract for future single-project write commands to adopt; not yet retrofitted into existing read paths (intentional — avoids UX regressions for callers that rely on implicit fan-out).
• cli._apply_firewall_flags() — pure function that builds a fresh PermissionPolicy from the flags + any persisted policy. Merge-without-duplicates on the deny list; preserves persisted mode and allow. Never mutates the persisted policy by reference.
• permissions.OPERATION_REGISTRY picked up two new entries (project.use / project.current). The existing fail-closed "unknown op defaults to write" behavior in _matches_pattern() means the flags already cover any new commands future PRs forget to register.

Three-layer boundaries respected: no HTTP in services, no business logic in commands, no Typer imports in services.

Test plan

• Unit tests (43 new, all pass):
  • tests/test_services.py::TestUseAndCurrentProject — 15 tests covering use_project, current_project, resolve_pinned_alias (every precedence branch, including stale-pin repair).
  • tests/test_helpers.py::TestResolveProjectAlias + TestApplyFirewallFlags — 12 tests covering the CLI adapter + the firewall-merge helper (fresh synthesis, merge-with-persisted-no-duplicates, persisted-not-mutated, both-flags-compose).
  • tests/test_cli.py::TestProjectUse + TestFirewallFlags — 16 tests covering CLI wiring: JSON and human output, env override reporting, exit codes, persisted policy gates project use, read-classified project current bypasses deny cli:write.
• E2E against live project 1143 (connection.europe-west3.gcp.keboola.com), new focused class TestPinAndFirewallE2E — 5 tests, all pass:
  • test_pin_lifecycle_against_real_project — add → current → use → verify persistence + env override
  • test_deny_writes_blocks_real_write_op — storage create-bucket blocked (exit 6), defensive post-check via direct API confirms the bucket was NEVER created
  • test_deny_destructive_blocks_real_destructive_op — storage delete-bucket blocked (exit 6)
  • test_deny_destructive_allows_read_op — storage buckets succeeds under --deny-destructive
  • test_firewall_flags_never_persist — post-run config.json inspection confirms permissions is still None
• ruff check + ruff format --check clean.
• Full unit suite: 1867 passing, 10 pre-existing Windows-only POSIX-permission-bit failures (present on main too — not regressions).

Live E2E tail

tests/test_e2e.py::TestPinAndFirewallE2E::test_pin_lifecycle_against_real_project PASSED [ 20%]
tests/test_e2e.py::TestPinAndFirewallE2E::test_deny_writes_blocks_real_write_op PASSED [ 40%]
tests/test_e2e.py::TestPinAndFirewallE2E::test_deny_destructive_blocks_real_destructive_op PASSED [ 60%]
tests/test_e2e.py::TestPinAndFirewallE2E::test_deny_destructive_allows_read_op PASSED [ 80%]
tests/test_e2e.py::TestPinAndFirewallE2E::test_firewall_flags_never_persist PASSED [100%]

============================== 5 passed in 2.99s ==============================

The comprehensive TestFullE2E::test_full_cli_e2e flow was also exercised end-to-end against project 1143; it got 80% through before hitting a pre-existing Windows-only download-table temp-file PermissionError unrelated to this PR. PR5's new step _test_project_pin_and_firewall is integrated into that flow (step 42.5) and runs the same assertions as the standalone class.

Pre-PR review loop

Three Explore agents run in parallel on the final diff (wire-contract / silent-failure audit / coverage gaps). Consolidated findings:

Wire contract

• Reviewer flagged CRITICAL: cli:destructive pattern not broad-expanded. Rejected as intentional — the two flags exist precisely so --deny-destructive can be narrower than --deny-writes (block destruction, allow builds). Confirmed by test_deny_destructive_allows_write. Added an inline comment in cli.py::_apply_firewall_flags() documenting the design.
• All other wire-contract checks passed: PermissionPolicy construction matches models.py, ConfigStore.save() is atomic, OPERATION_REGISTRY entries correctly classified, remove_project() auto-rotation still works post-use_project.

Silent-failure audit

• No PR feat(0.21.0): sync push deploys config rows + first-class variables UX #190 / feat(0.22.0): job run auto-resolves variableValuesId from linked variables #191-class bugs found. One LOW finding: KBAGENT_PROJECT="" silently treated as unset — intentional (Unix shell convention, keeps CI callers that conditionally export the var unsurprised). Documented in a code comment.

Coverage gaps

• 3 critical/high gaps closed before commit:
  • project current Rich human-mode output — added test_project_current_human_mode_with_pin + test_project_current_human_mode_env_warns_unknown.
  • project.use permission gate untested — added test_project_use_blocked_by_persisted_deny_writes.
  • resolve_pinned_alias stale-pin branch untested — added test_resolve_pinned_alias_points_to_unregistered.
• Medium finding (the helper is not yet wired into existing write commands): deferred — intentional, commented in the helper's docstring as a public contract for future PRs.

Replacing with English version for broader team visibility.

[padak]

Approve — merge-ready

Security-wise correct (permission registry complete, the firewall merge is additive, the REPL fix correctly forwards flags, mutation safety is tested). Test coverage is ~40 new tests including E2E against a live API. No blockers.

Nice-to-have (follow-up PR)

1. Add a section to plugins/kbagent/skills/kbagent/references/permissions-workflow.md — "Session firewall flags" — a security topic deserves its own place in the references:

• WIDE (--deny-writes blocks write+destructive+admin) vs NARROW (--deny-destructive blocks only data destruction)
• REPL forwarding behavior
• Relationship to persisted policy (additive merge, never relaxes)

2. Add to gotchas.md about the KBAGENT_PROJECT env var:

• Empty string = unset
• Points-to-unregistered alias → fail hard with CONFIG_ERROR
• Precedence: --project > KBAGENT_PROJECT > pin > sole-project fallback

3. --hint for project use/current — if the hint framework can render ConfigStore mutations, add it; otherwise skip with a comment (local-only operation).

4. src/keboola_agent_cli/cli.py:90-144 _apply_firewall_flags — the underscore prefix + cross-module import from commands/permissions.py = leaky API boundary. Either rename to apply_firewall_flags, or move it to permissions.py as a public helper.

Positives

• WIDE vs NARROW semantics after iter-4 review are precisely specified in the help string and documentation.
• resolve_pinned_alias() + resolve_project_alias() is a well-designed public API; future PRs can adopt it.
• test_flags_do_not_mutate_persisted explicitly locks the invariant "session flags never subtract from the persisted policy".
• REPL forwarding is non-trivial (duplicate guard) and is tested.

[ottomansky]

Bundled all four follow-ups on this branch (simpler than a separate follow-up PR):

• docs(references): add Session firewall flags section to permissions-workflow.md — e851025 — WIDE vs NARROW, REPL forwarding, additive-merge relationship to persisted policy.
• docs(gotchas): document KBAGENT_PROJECT env var semantics and precedence — 562c776.
• chore(hints): clarify project use/current are local-only (no --hint) — 87e66f6 — decided --hint has no meaningful output for local-only ConfigStore mutations (no client/service call to render). Added an inline comment at each command definition documenting the rationale.
• refactor(cli): promote _apply_firewall_flags to public apply_firewall_flags — 77f402d — rename-in-place (body has zero Typer coupling but cli.py is still the cleaner home). Updated 2 call sites + 8 test references.

Targeted tests: 30/30 pass. make lint format-check skill-check version-check changelog-check all green.