Skip to content

feat(runtime): guide Auto tool selection by final tool surface - #3705

Open
testikun wants to merge 1 commit into
apache:mainfrom
testikun:codex/issue-3507-auto-tool-guidance
Open

feat(runtime): guide Auto tool selection by final tool surface#3705
testikun wants to merge 1 commit into
apache:mainfrom
testikun:codex/issue-3507-auto-tool-guidance

Conversation

@testikun

@testikun testikun commented Aug 24, 2026

Copy link
Copy Markdown

Closes #3507

What changed

  • Add a pure Auto tool-guidance resolver in packages/runtime/src/system-prompt/auto-tool-guidance.ts.
  • Resolve eligibility from the Host permission snapshot and the final model-visible tool surface, after routing, profiles, plan filtering, and capability projection.
  • Inject the guidance only into the normal Interactive main-session prompt. Child instructions, Side Conversations, Deep Research, bound tool ceilings, broken shells, fixed profiles, and non-Auto modes remain unchanged.
  • Advertise only structured tools that are actually exposed, and explicitly state that Bash cannot bypass Maka sandbox, workspace, network, or approval boundaries.
  • Bump the Interactive Composer revision and add resolver/composer regression coverage.

Scope

This changes prompt guidance only. It does not change permission classification, sandbox or approval execution, Bash schema/implementation, persistence protocols, or the headless-coding-v1 contract.

Verification

  • Runtime full suite: 3010 tests, 2997 passed, 13 skipped, 0 failed.
  • Runtime Host full suite: 1137 passed, 0 failed.
  • Focused guidance/composer tests: 34 passed.
  • Runtime and Runtime Host builds/typechecks, root lint, format check, ASF header check, and git diff --check passed.

AI use

  • Generative tooling made a substantive contribution

Tool: OpenAI Codex assisted with issue analysis, implementation, tests, and verification.

@testikun
testikun force-pushed the codex/issue-3507-auto-tool-guidance branch 3 times, most recently from 18a5aba to 191282e Compare August 24, 2026 12:15

@yunaremaia yunaremaia left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice, clean slice — the eligibility matrix is well chosen (bypass needs no anti-bypass guidance, explore has no mutation tools to name), the fragment is deterministic and pure, and the tests cover both the positive path and every exclusion branch including the partial-tool-surface case. The bump of INTERACTIVE_RUN_COMPOSER_REVISION for the prompt-shape change is also the right call.

One coupling worth making explicit while this is fresh:

The Bash gate lives two checks away from its supporting fact. In interactive-run-composer.ts you compute

shellAvailable: input.shell?.setupError === undefined,

which maps an absent shell to undefined rather than false. The resolver then only treats literal false as disqualifying, so a session with no shell at all still passes the shellAvailable check — it survives solely because a missing shell also removes 'Bash' from tools, and resolveAutoToolGuidance independently requires toolNames.includes('Bash'). That's correct today, but the safety of the first check depends on an invariant maintained by a different subsystem (whatever guarantees "no shell ⇒ no Bash tool entry"). If that ever drifts — say a future surface exposes a remote-shell Bash entry without a local input.shell — the guidance would advertise shell-first workflows into a session that cannot run them, and nothing here would fail loudly.

Two cheap ways to pin it down; either works:

  1. Treat absence as absence: pass shellAvailable: input.shell !== undefined && input.shell.setupError === undefined and keep the resolver's === false check (or switch both to truthiness). One expression, no cross-module assumption.
  2. Keep the current wiring but add one line to the resolver doc comment stating that shellAvailable === undefined means "unknown" and eligibility then rests entirely on the toolNames gate — so the next reader knows the pairing is intentional.

Not blocking — behavior is correct as written — but I'd sleep better with option 1.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use mode-aware CLI-first tool guidance in Auto mode

2 participants