[sanchitrk]

Summary

• Contract (@codeworksh/plugin): tools take an optional exposure: direct (the default), model, codemode, deferred or hidden, defined as the ToolExposure schema. declared(def) is the single rule for which tools the model can see, and only direct and model pass it. Pi calls the model value model-only; we use single words for all five.
• Registration: a plugin that registers an unknown exposure value fails inside its own setup.
• Catalog: the request's tool list, the tool definitions and the executor cover only declared tools, so a call to any other tool gets the existing Unknown tool: <name> error. Registry.defs, names and getDef still list every tool, so a later tool search can find deferred ones.
• Prompt:
  • <tools> and the tool guidelines already follow the resolved snapshot, so they need no change.
  • The bash file-ops rule names only declared tools.
  • The skills hint names only a declared read or bash, and <skills> is left out when neither is declared. This matches Pi.
• Docs and changelog: an exposure row in the plugin authoring docs, and Unreleased CHANGELOG notes for the plugin and harness packages.

This change doesn't load deferred tools yet; the follow-up adds resolve(loaded) and tool search. Codemode calls and the MCP exposure mapping are also out of scope.

Tests

• runner.loop.test.ts "tool exposure", artifact __artifacts__/tools.exposure.json:
  • Both requests carry only direct and model tools.
  • <tools> and the rules leave the other exposures out.
  • Overriding bash as hidden removes the bash rule.
  • A call to a deferred tool returns Unknown tool.
• plugin.skill.test.ts, artifact __artifacts__/prompt.skill.exposure.json, using example skills under .agents/skills:
  • read hidden: the hint names bash.
  • read deferred and bash codemode: no <skills>.
  • read as model: the hint names read.
• vp check and vp run typecheck pass, and so do the five related harness suites (57 tests).

🤖 Generated with Claude Code