feat(integrations): align agent guidance and tool routing

[knqiufan]

Which issue or RFC does this PR close?

Closes #1520. Implements D of #1450 without closing the parent tracker.

Rationale for this change

Agents see tools before loading a Skill. Conflicting guidance can turn a historical lookup into inventory, report Source capture as a saved Memory, or treat a temporary handoff as permission to commit a durable milestone. Guidance must describe the capabilities actually available in each host and distinguish a selected tool, a successful operation, and a truthful completion report.

What changes are included in this PR?

• Align system guidance, tool descriptions, and existing Skills across DSH, Pi, OpenCode, OpenClaw, Hermes, MCP-backed Codex/Claude Code/WorkBuddy, and the portable Agent Plugin. Preserve existing Skill names and native approval boundaries.
• Separate search from inventory, explicit Memory writes from Source capture, previews from writes, temporary Handoffs from durable commits, and candidate inspection from approval or execution. Inject Pi guidance even when recall fails or returns no context, provide MCP initialization instructions, and make OpenClaw guidance availability-aware.
• Integrate master 847203dc, including feat(dsh): expose observed recall and capture status through /pc #1600. Reflect the already-available Pi Topic Memory, candidate/artifact inspection, Work Contract, Handoff acknowledgement, and Task Outcome tools, plus OpenClaw's work tools. These tools are existing master capabilities, not newly introduced backend APIs in this PR.
• Make Handoff arguments and result paths explicit. High-level current-work operations capture their own Source; low-level flows capture, prepare or activate, then finalize the exact returned Draft. Add structured finalize schemas, distinguish declared facts from verified citations, and specify next_action, omissions, and OpenClaw's top-level Source ID. Rebuild checked-in bundles and regenerate OpenAPI descriptions.
• Execute registered DSH/Pi/OpenCode and built OpenClaw Handoff adapters against controlled HTTP replies in evaluation. Record actual argument selection, generated Source identity, injected Scope, and response wrappers. Reject invalid requests, invented evidence, changed Drafts, unfinished carriers, and unauthorized commits. Accept omitted optional null metadata while preserving mandatory fields and exact receipts.
• Validate Memory-call arguments and require explicit transcript-bound reporting review before acceptance can pass. Error diagnostics identify fields such as handoff.state[0].basis/evidence. Add regressions for false-positive acceptance and run native adapter regressions in package CI.
• Preserve launchd registration/retry diagnostics before native-test cleanup, with a startup-failure diagnostic regression. Native lifecycle deadlines and acceptance assertions remain intact.

Are there any user-facing changes?

Agents receive consistent intent and completion guidance before and after Skill loading. Ordinary handoff requests produce a temporary carrier; durable commits still require an explicit durable-milestone request. Existing tool names, HTTP field shapes, persisted formats, Scope isolation, and host authorization remain compatible. OpenAPI changes are descriptions only.

The bilingual qualification record and all 276 observations distinguish runtime evidence from model behavior. The current composite Handoff sample is 106/108 for valid sequences/carriers and 105/108 after explicit Codex reporting review. Two samples use verified facts without evidence; one strengthens “no code changes” into “no code changes required.” These remain failures. The failed-write/missing-tool sample is 16/24 after review, including all 12 failed-write cases correctly reporting no save. Missing-tool hallucinations and substitute-persistence suggestions remain unqualified.

These measurements do not certify automatic Skill discovery, real permissions in every host, or strict bare-carrier formatting; some replies include the complete carrier inside a response wrapper. Guidance is not an authorization mechanism. Layered Skills and naming/distribution remain separate workstreams.

How was this change tested?

• uv run pytest tests/test_integration_guidance_evaluation.py tests/test_api_generation.py tests/test_api_contract.py tests/test_integration_manifest.py -q: 102 passed, including 28 evaluator regressions and real adapter request/response checks.
• uv run pytest tests/test_mcp.py tests/integrations/test_hermes_provider.py -q: 85 passed. JavaScript operation contract tests: 3 passed.
• Package suites: DSH 256, Pi 93 (including real CLI), OpenCode 53, OpenClaw 73 passed. Package type checks/builds passed. OpenClaw uses Node 24.15.0, required by the pinned SDK.
• Real DSH SDK runtime suite: 5 passed; rebuilt SDK catalog export also passed.
• API/JavaScript generation checks and description-free comparison against master passed. Applicable pre-commit hooks and Linux-platform Python type checking passed. Local ty-check excludes unrelated untracked personal files and existing Windows-only type errors; CI runs the normal quality job.
• Live Step 3.7 Flash runs use exported catalogs, bilingual cases, three Skill conditions, controlled replies, and explicit reporting review. All failures and intermediate batches remain recorded; no real Server persistence is performed by this evaluator.
• All 20 checks passed on 281bec20: Python 3.11–3.14, SQLite/OceanBase acceptance, Linux/macOS/Windows native lifecycle, website and Windows link validation, all integration packages, quality, license, and CLA. Main CI run. CI success and the explicitly limited live-model qualification above are separate results.

AI usage statement

OpenAI Codex (GPT-6 Astra) assisted with implementation, review, documentation, and tests. Step 3.7 Flash was used for recorded live-model evaluations. Transcript reporting review was performed by Codex, not a human reviewer. Native runtime execution, controlled adapter execution, and model-catalog measurements are distinguished in the evidence.

[Teingi]

resolve conflicts

[Teingi]

LGTM

[Teingi]

resolve conflicts