feat(agents): scope helper cost permission to live host

[decode2]

Linked issue

Refs #1702 (approved). Internal cost-permission coordinator; public wiring and actual nested-SDK proof remain next-unit work.

Stack

After #1735, base feat/1702-bounded-helper. Includes its inherited SDK-readiness fix through feature-only branch integration. No main merge.

PR type

• New feature (type:feature)

Summary

• Add supported closed SDK UI choices for model-cost permission only, scoped to live manager/session/cwd/model/registry and logical published target.
• Share core preflight to reject invalid/oversized input before dialogs; bound scopes and single pending request, revoke/clear with epoch invalidation.
• Retain any still-billable old-engine lease across cancellation/scope/registry changes, with fresh host/public-source checks.

Changes

Path	Change
lib/orchestrator-helper-consent.ts	Ephemeral exact-host model-cost coordinator and closed choices
lib/orchestrator-helper.ts	Shared preflight and busy inspection, preserving bounds
tests/orchestrator-helper-consent.test.ts	Seven deterministic simulated UI/scope/lease cases
Docs and ODD tracker	Actual contract, incomplete public integration and evidence

Test plan

• Import-boundary failure214pass/1fail is recorded honestly, not claimed registered-mode behavioral RED.
• Eight-file coordinator/helper/metadata/state/catalog/discovery/presence/agents suite:221pass,0fail.
• After SDK-readiness feature-parent update: coordinator/core/actualmetadataSDK focused15pass,0fail.
• Actual metadata SDK regression1pass; NOT actual nested-helper or human-approval proof.
• Type check186baseline diagnostics,no regressions; runtime8modulesmatch; whitespacecheckpasses.
• Fresh committed-range assessment338lines,medium,runtime large writer,underbudget; self-verification stands,no required separate verifier. Native outcome unknown,not closed.

Permission boundaries

Only supported UI choices allow once or same logical target/current model for this session. Headless/unknown/declined choices cannot grant. Exact manager identity/sessionID/cwd/model object/provider/id/registry must remain current; source digest/recentness is revalidated after the dialog. Revocation invalidates pending choices and cancels without releasing a still-billable lease. At most8target scopes are cached, ephemeral only.

UI choices here are simulated fixtures, not real human consent evidence. Host integration MUST supply genuine live SDK context/currentness and clear lifecycle permissions. Messaging grants, metadata decision text, model prose and child replies grant nothing.

Remaining work

Public reasoning/revocation modes, lifecycle hookup and actual nested-helper SDK validation are deliberately deferred. Metadata/public tools are unchanged. Both issues remain open.

Contributor checklist

• Approved issue linked nonclosing; exactly one selected type label.
• Code/tests/docs/conventional commit,no attribution trailers.
• Shellcheck and changed-skill checks not applicable.
• Remote checks pending after publication.

No paid/outbound models, merge into main, auto-merge or reload authorized.

Summary by CodeRabbit

• Documentation
  • Added guidance on helper authorization choices, including one-time approval and approval scoped to a target and session.
  • Documented safeguards for unavailable or outdated requests, permission revocation, cancellation, and session cleanup.
  • Clarified that this integration is not yet connected to the main orchestration flow; broader integration work remains outstanding.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: fd500453-cab4-4ba5-b66f-143d9c120067

📥 Commits

Reviewing files that changed from the base of the PR and between 8d03615 and b5f3475.

📒 Files selected for processing (5)

• docs/gentle-agents-activity.md
• lib/orchestrator-helper-consent.ts
• lib/orchestrator-helper.ts
• odd/tasks/agent-coordination.md
• tests/orchestrator-helper-consent.test.ts

 _________________________________
< My bunny whiskers are tingling. >
 ---------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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