fix(skills): drop the last undefined tool reference, guard the class in CI (#493)

[yinlianghui]

Description

customer_360 declared tools: ['search_knowledge'] — the survivor of the eleven fictional tools #493 counted, missed by #512 because that skill looked "already correct". The runtime silently drops an unresolved tool, so the skill shipped with its only declared capability resolving to nothing, while its instructions promised an account + cases + opportunities + knowledge roll-up it had no tool to read.

Took option 2 (remove the reference) from the scoping comment, because option 1 cannot work. Per ToolSchema in @objectstack/spec@16.1.0:

[READ-ONLY PROJECTION — not an execution entry point] Authoring a tool as metadata does NOT make it runnable: this schema has no implementation/handler field and no framework executor loads a metadata-authored tool.

A hand-authored search_knowledge would validate, build, and still never run. And the knowledge base here is not a search service — it is crm_knowledge_article, a normal CRM object, so query_records reaches it exactly like every other object the skill reads.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement
• CI/CD update

Related Issues

Fixes #493
Related to #512, #515

Changes Made

• customer_360 — search_knowledge → describe_object / get_record / query_records / aggregate_data. Instructions rewritten to actually deliver what the description promises: contacts, open cases, open opportunities, and published crm_knowledge_article rows matched on the categories/tags of the cases just read, with totals from aggregate_data instead of hand-summed rows.
• test/skills-integrity.test.ts (new file, per the scoping comment — metadata-references.test.ts is a busy merge surface):
  • every skill tool resolves to a platform built-in or an action_<name> tool materialised from a real Action, with wildcard subscriptions resolved by prefix;
  • every referenced Action is ai.exposed with a ≥40-char LLM description and a headless path (flow with a defined target, or a script body) — the regression refactor(ai): skills-only AI surface — real Actions instead of 10 fictional tools, retire the two agents #512's follow-up commit had to fix by hand;
  • stack tool metadata cannot be used to satisfy a dangling reference, since it never executes;
  • every skill handed off to in instructions exists — the defect that pointed case_triage at a response_drafting skill that was never defined.
• Two stale docstrings corrected. case_triage and email_drafting justified their read-only posture by calling escalate_case, close_case and send_email type: 'modal' with no headless path. fix(ui): resolve dead references, unresolvable tokens, and unreachable surfaces (#491) #515 and the send_email rewrite retyped all three to flow/script. The posture is right, the stated reason was wrong — none of the three opts in via ai.exposed (ADR-0011 is opt-in, default off), so no tool is materialised and the human review step stays a deliberate governance call rather than a mechanical limit.

On the built-in allowlist

The AI runtime ships in the closed cloud package (ADR-0025 §2), so open-edition node_modules has no authoritative tool list to resolve against. The allowlist is therefore explicit and annotated with its provenance: the read subset of the tool surface the @objectstack/mcp@16.1.0 bridge registers (verifiable locally), plus visualize_data. The raw write tools (create_record / update_record / delete_record) are deliberately excluded — HotCRM's state changes go through Actions so validation, sharing rules and audit match the UI path, and this list is where a skill reaching past them gets caught.

Testing

• Unit tests pass (npx vitest run) — 12 files, 146 tests (+6)
• Linting passes (npx objectstack lint --skip-i18n) — 1 warning, 9 suggestions, all pre-existing
• Build succeeds (npx objectstack build), and objectstack validate passes with the 2 pre-existing campaign_enrollment flow-variable warnings
• Manual testing completed — each guard verified against the real defect before landing: reinstating search_knowledge, adding action_escalate_case (a non-exposed Action), and repointing the hand-off at response_drafting each fails its own assertion with a readable message
• New tests added (if applicable)

Checklist

• I have added a changeset (.changeset/skills-undefined-tool-references.md, patch)
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Additional Notes

Two things a reviewer may want to weigh in on:

1. visualize_data is the one allowlist entry with no local evidence — it appears nowhere in the installed 16.1.0 bundle. It was adopted by revenue_forecasting in refactor(ai): skills-only AI surface — real Actions instead of 10 fictional tools, retire the two agents #512 against upstream's validate-ai-tool-references rule (objectstack#3894), which reported 0 findings, so I kept it and documented the basis rather than removing a tool on weaker evidence than the maintainers had. If it turns out not to be served, deleting it from PLATFORM_TOOLS makes the guard fail loudly and points straight at the skill.
2. docs/developers/code_examples.md still documents an src/agents/ directory and a permissions: [...] key on skills, both retired by refactor(ai): skills-only AI surface — real Actions instead of 10 fictional tools, retire the two agents #512 / fix(skills): drop the per-skill permissions keys — the field does not exist in SkillSchema #511. Left alone as out of scope for this issue, but it is real doc drift worth a follow-up.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Y9STuduWbrAwcgviziaV4e

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hotcrm	Ignored		Jul 31, 2026 2:27am