fix(approval): turn-boundary deliberation one-shot + destructive-tool registry

[elkaix]

Related Issue

None linked. Implements M5 + M6 from docs/superpowers/plans/2026-06-02-deliberation-turn-boundary.md.

Description

This PR fixes auto-deliberation turn-boundary handling for destructive actions.

Covers:

• destructive-tool classifier registry seam
• DeliberationScope ContextVar primitive
• context/generation-scoped auto_deliberate one-shot handling
• production scope propagation into tool futures
• same-response duplicate and subagent isolation regressions
• stale/out-of-order generation preservation regression
• CHANGELOG entry under ## Unreleased

Verification

• uv run pytest tests/ -q -p no:cacheprovider --ignore=tests/e2e --ignore=tests/ai
• uv run pyright
• uv run ruff check .
• uv run ruff format --check .
• uv run pytest tests/core/test_approval_auto.py::test_same_generation_duplicate_destructive_calls_both_bounce tests/core/test_approval_auto.py::test_subagent_identical_call_does_not_consume_main_one_shot -v
• cd docs && npm run sync
• local changelog workflow simulation: 4 added nonblank ## Unreleased lines
• uv run pytest tests/test_release_update_pipeline.py::test_changelog_workflow_skips_release_prep_prs -q
• git diff --check

Checklist

• Root cause investigated from PR checks and logs
• Shipped-code changelog entry added
• Docs changelog regenerated with cd docs && npm run sync
• Focused regression tests included
• Formatting/lint/type/test gates recorded above

Summary by CodeRabbit

• New Features

  • Improved auto-mode handling of dangerous operations: duplicate dangerous commands in the same LLM response are now rejected, while deliberate retries and subagent operations are processed independently.

• Documentation

  • Updated changelog to reflect auto-mode destructive action behavior changes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ebcdedf8-19b7-4cc7-b047-728965b6d484

📥 Commits

Reviewing files that changed from the base of the PR and between eea2b93 and 34809ff.

📒 Files selected for processing (2)

• CHANGELOG.md
• docs/en/release-notes/changelog.md

---

📝 Walkthrough

Walkthrough

This PR introduces generation-scoped deliberation context to make destructive-action one-shot bouncing aware of execution context and generation identity. The feature unifies context-specific approval fingerprinting with per-generation bounce tracking, allowing the same destructive call to be approved in a later generation even if it was rejected in an earlier one.

Changes

Deliberation Scoping for Context-Aware One-Shot Approval

Layer / File(s)	Summary
Deliberation Scope Infrastructure src/pythinker_code/soul/approval.py	DeliberationScope dataclass and deliberation_scope(...) context manager backed by ContextVar bind execution identity. ApprovalState.deliberated_fingerprints is converted from set[str] to dict[str, int] to track generation per fingerprint.
Scoped One-Shot Approval Gating src/pythinker_code/soul/approval.py, tests/core/test_approval_auto.py	_deliberation_fingerprint(...) now incorporates context_id into the stable identity. deliberation_gate(...) implements generation-scoped semantics: same-generation duplicates bounce, later generations in the same context allow once then bounce, earlier generations remain rejected. Tests cover all three cases plus end-to-end request/retry flow.
Destructive Tool Classifier Refactoring src/pythinker_code/soul/permission.py, tests/core/test_approval_auto.py	_shell_args_destructive_reason() extracts the command argument. tool_destructive_reason() uses a _DESTRUCTIVE_CLASSIFIERS dispatch map instead of hard-coded Shell logic. Tests verify background tool gating and unregistered tool handling.
PythinkerSoul Step Deliberation Integration src/pythinker_code/soul/pythinkersoul.py, tests/core/test_pythinkersoul_steer.py	_deliberation_generation counter and per-step deliberation_context_id computation derived from approval source (kind/id, agent_id, subagent_id, or role+session). Wraps pythinker_core.step(...) and result.tool_results() in deliberation_scope(context_id, generation) to bind context through the entire step execution, including lazy tool-result futures. Integration test verifies scope binding via asyncio tasks.

Sequence Diagram

sequenceDiagram
  participant PythinkerSoul
  participant deliberation_scope as deliberation_scope CM
  participant Core as pythinker_core.step
  participant Approval
  participant ApprovalState
  
  PythinkerSoul->>PythinkerSoul: increment _deliberation_generation
  PythinkerSoul->>PythinkerSoul: compute deliberation_context_id
  PythinkerSoul->>deliberation_scope: enter(context_id, generation)
  Note over deliberation_scope: Bind DeliberationScope to ContextVar
  deliberation_scope->>Core: execute pythinker_core.step(...)
  Core->>Approval: may invoke destructive actions
  Approval->>deliberation_scope: read active DeliberationScope
  Approval->>Approval: compute fingerprint(context_id, tool_name, args)
  Approval->>ApprovalState: check deliberated_fingerprints[fingerprint]
  alt Same generation duplicate
    ApprovalState-->>Approval: generation matches
    Approval-->>Core: return rejection (bounce)
  else Later generation in same context
    ApprovalState->>ApprovalState: record new generation, delete old
    Approval-->>Core: return None (allow once)
  else Earlier generation or unscoped
    ApprovalState-->>Approval: prior bounce recorded
    Approval-->>Core: return rejection (bounce)
  end
  Core-->>deliberation_scope: return StepResult
  deliberation_scope->>deliberation_scope: await tool_results (scope bound)
  deliberation_scope-->>PythinkerSoul: exit scope

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Pythoughts-labs/pythinker-code#50: Adds the auto_deliberate auto-mode and thinking-effort plumbing that feeds into the scoped destructive-action approval flow updated in this PR.

Suggested labels

bug

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 38.71% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title follows conventional commits format with valid type (fix), scope (approval), and clearly describes the main changes: one-shot scope fix and destructive-tool registry.
Description check	✅ Passed	Description covers related issue context, detailed explanation of changes across all affected modules, comprehensive verification steps, and completed checklist items per template.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/deliberation-turn-boundary

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}