[helpcodeai]

Summary

Lets an agent propose a saved code tool that a workspace admin then reviews and approves, closing the loop from PR #1366 where only an admin could hand-author a code tool. Builds on the KgSkillSuggestion.kind hook that PR added. Tracks #1369.

• code_propose_tool (new per-server MCP tool): gated exactly like inline code (codeMode = 'inline' + the inlineCode role capability + a configured runner). It does not run code and does not create a tool — it records an inert KgSkillSuggestion with kind = 'code', source = 'agent', always invoker + read-only, and only over the proposer's own visible connectors. An agent can never raise its own authority.
• Approval: a code proposal shows up for admins under Knowledge → Skills, marked as a code-tool proposal with its program shown. "Create tool" goes through the existing tool-creation path (assertValidCodeTool + plan cap, admin's own auth); writes / definer are added only by editing the tool afterwards, where Enterprise/admin gating applies again. apply() refuses a code proposal on purpose.
• Never served as a skill: kind = 'code' is excluded in visibleWhere, the single query behind every skill-delivery path.
• Schema: one additive, nullable kg_skill_suggestions.payload column (metadata-only in Postgres). Off by default; no-op for existing installs.

Cloud vs self-hosted

Identical behaviour in both. The proposal tool only appears when a server opted into inline and the caller's role carries the capability (the Cloud shared /mcp endpoint never exposes it, like all code mode). No new cross-tenant surface: proposals reference only the proposer's connectors and are created through the same org-scoped tool path.

Testing (worktree, packages/backend unless noted)

• npx tsc --noEmit -p tsconfig.json — backend: clean; frontend (packages/frontend): clean.
• npm run lint — backend: 0 errors (11 pre-existing warnings in unrelated files); touched files clean.
• npx jest src/knowledge-graph src/mcp-server src/roles — 801 passed, 2 skipped (live runner), 1 suite skipped.
• npx jest src/knowledge-graph/kg-skill.service.spec.ts — 39 passed (new: proposal stored invoker/read-only with payload; empty name/code/connectors rejected; apply() refuses a code proposal; kind = 'code' excluded from active-skills query).
• Migration: applied all migrations to a throwaway Postgres 17 (prisma migrate deploy, success) and prisma migrate diff DB→schema reports "No difference detected."
• Docs updated (docs/code-mode.md) and llms regenerated (node scripts/generate-llms-txt.mjs --check clean).

Notes

No ee/ changes. Follows the off-by-default, fail-safe pattern of PR #1366. The schema change was discussed first in #1369 per AGENTS.md.