Skip to content

docs(delegation): align guidance with current contract - #66556

Closed
helix4u wants to merge 2 commits into
NousResearch:mainfrom
helix4u:docs/delegation-current-contract
Closed

docs(delegation): align guidance with current contract#66556
helix4u wants to merge 2 commits into
NousResearch:mainfrom
helix4u:docs/delegation-current-contract

Conversation

@helix4u

@helix4u helix4u commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

What does this PR do?

Aligns the delegation documentation and model-facing tool description with the contract currently shipped on main.

PR #56386 intentionally removed model-controlled toolsets from delegate_task so children inherit the parent's enabled capabilities. The feature reference, delegation guide, Chinese translations, and several live description strings still advertised that removed argument. The same pages also described top-level delegation as synchronous even though #49734 made top-level model dispatch background by default.

This update removes the invalid call shapes and documents the current lifecycle without changing runtime behavior. PR #55010 remains the separate proposal to restore an explicit background=false escape hatch.

Related Issue

Follow-up to #56386 and #49734. Related behavior proposal: #55010.

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 🔒 Security fix
  • 📝 Documentation update
  • ✅ Tests (adding or improving test coverage)
  • ♻️ Refactor (no behavior change)
  • 🎯 New skill (bundled or hub)

Changes Made

  • Remove model-facing toolsets arguments from English and Chinese delegation examples.
  • Explain that children inherit the parent's enabled toolsets and still lose child-blocked tools.
  • Document automatic top-level background dispatch, synchronous orchestrator children, stateless-endpoint fallback, and ownership-based cancellation.
  • Correct the live delegate_task description to advertise one batch handle and one consolidated result instead of nonexistent per-task handles.
  • Remove stale toolsets references from the Python docstrings and dynamic schema descriptions.

How to Test

  1. Parsed all 24 changed python documentation blocks with ast.parse — passed.
  2. Imported the live dynamic schema with an isolated temporary HERMES_HOME and verified that neither schema shape exposes toolsets, the description advertises one batch handle/consolidated result, and the stale parameter wording is absent — passed.
  3. Ran git diff --check — passed.
  4. Website production build was not run in the clean worktree because Node dependencies were not installed; GitHub CI owns the full documentation build.

Checklist

Code

  • I've read the Contributing Guide
  • My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
  • I searched for existing PRs to make sure this isn't a duplicate
  • My PR contains only changes related to this fix/feature (no unrelated commits)
  • I've run pytest tests/ -q and all tests pass — not run for this documentation-only correction; focused validation is listed above
  • I've added tests for my changes (required for bug fixes, strongly encouraged for features) — N/A: no runtime behavior changed
  • I've tested on my platform: Windows 11 (documentation examples and live schema contract)

Documentation & Housekeeping

  • I've updated relevant documentation (README, docs/, docstrings) — or N/A
  • I've updated cli-config.yaml.example if I added/changed config keys — N/A: no config change
  • I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — N/A: no architecture or workflow change
  • I've considered cross-platform impact (Windows, macOS) per the compatibility guide — documentation/schema text only
  • I've updated tool descriptions/schemas if I changed tool behavior — the stale description was corrected; runtime behavior is unchanged

Screenshots / Logs

N/A — documentation and model-facing description correction.

@teknium1

Copy link
Copy Markdown
Contributor

Salvaged and merged as #66576 (rebased so your commit keeps authorship). I added one small follow-up commit cleaning up two stale internal comments in delegate_tool.py that still described the superseded "N independent handles" batch model. Verified all four contract claims against current main (no model-facing toolsets, background-by-default top-level dispatch, batch = one consolidated result, no delegate_task_async) plus a live E2E on the dynamic schema. Thanks @helix4u — this directly fixes the docs that misled the skill author in Discord.

@teknium1 teknium1 closed this Jul 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low — cosmetic, nice to have tool/delegate Subagent delegation type/docs Documentation improvements

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants