Code mode: agent-proposed code tools (code_propose_tool → admin approval) #1369

Summary

Let an agent propose a saved code tool (endpointMapping.method = 'code') that a workspace admin then reviews and approves, instead of an admin hand-writing every code tool in the tool editor. This closes the loop started in #1363: code tools exist and run, but today only an admin can author one. An agent that has discovered a useful multi-step pattern should be able to suggest codifying it, under human approval.

This is deferred from the initial code-mode delivery (PR #1366) on purpose: it needs its own review because it adds an agent-facing write path and (small) schema work. Per AGENTS.md this issue is the "discuss before a schema change" step — no code until the design here is agreed.

What already landed (the hook)

PR #1366 added KgSkillSuggestion.kind ('skill' default | 'code') precisely so an agent-proposed code tool can reuse the existing skill suggestion → admin approval flow rather than inventing a parallel one. The approval surface, storage and admin UI for skill suggestions already exist; this issue wires code proposals through them.

Design (proposed)

• Tool code_propose_tool (per-server, gated exactly like inline code: codeMode = 'inline' + the caller's role capability + a configured runner). It does not execute anything — it records a proposal.
• The proposal is stored as a KgSkillSuggestion with kind = 'code', carrying the candidate endpointMapping (program, uses, runAs, allowWrites) plus a human-readable rationale.
• Authority stays admin-side. The proposal is inert until an admin approves it in the existing suggestions UI; approval runs the same assertValidCodeTool guard as manual creation (definer ⇒ admin, allowWrites ⇒ Enterprise, uses same-org, plan cap). An agent can never raise its own authority: a proposed definer/allowWrites tool simply cannot be approved by a non-admin, and the program is validated before it ever becomes a real McpTool.
• Safe defaults on parse, same as the bridge: unknown/invalid fields fall back to no-writes, invoker.

Scope

• In: the code_propose_tool sandbox/discovery tool, the kind = 'code' suggestion path, the admin approval → McpTool creation reusing assertValidCodeTool, tests, docs.
• Out: any change to how approved code tools run (that is Code mode: saved code tools (McpTool endpointMapping.method = 'code') #1363/Code mode: out-of-process code-runner and backend executor client #1361, already merged); shared-endpoint exposure; Cloud operations.

Acceptance criteria

• An agent on a server with codeMode = 'inline' and the capability can call code_propose_tool; the proposal appears in the admin suggestions UI as a code proposal, never as a live tool.
• Approval creates the McpTool only when assertValidCodeTool + plan cap pass; a proposed definer/allowWrites tool cannot be approved by a non-admin.
• Off by default and on Cloud: no new exposure unless the server opted into inline and the role carries the capability — identical gating to inline code.
• Both Cloud and self-hosted behaviour documented in docs/code-mode.md.

References

• Builds on Code mode: saved code tools (McpTool endpointMapping.method = 'code') #1363 (saved code tools) and Code mode: inline code_execute and in-sandbox amcp.* discovery tools #1364 (inline + discovery), schema hook from Code mode: Prisma schema (code_runs, McpServerConfig.codeMode, Role.capabilities, KgSkillSuggestion.kind) #1362, all delivered in PR Add code mode: isolated code execution over MCP tools #1366.