Summary

Reopens the work from #2828 (closed) on the same branch , all 10 commits carry forward unchanged, plus this description reflects the final state after Greptile's review passes.

Fixes all 7 issues from Manufact's automated app-directory readiness check against Cedar's public MCP server (https://api.mail.cedarcopilot.com/mcp), ahead of submission to the Claude and OpenAI (Codex) app directories, then addresses everything Greptile's review turned up across two rounds.

The 7 original issues:

• tool-hints-present / tool-title-present / claude-tool-hints-present , every externally-registered MCP tool now declares a title and real-behavior-matched annotations.{readOnlyHint,destructiveHint,openWorldHint} via EXTERNAL_TOOL_METADATA in server.ts.
• claude-code-metadata-length , the 7 flagged tools trimmed under Claude Code's 2KB byte budget.
• policy-review (telemetry over-collection) , patched @armature-tech/mcp-analytics@0.6.36 so telemetry.agent_thinking reads as genuinely optional instead of coercive.
• policy-review (document tool scope) , the single document tool (one generic action selector spanning read alongside delete/share) is now document-read/document-write, the minimum split Manufact's finding asked for ("at minimum separating read/list/search from create/update, delete/restore, move, and share/revoke"), used identically by every internal and external consumer with zero special-casing , mirroring conversationTool.ts's existing conversation-read/conversation-write pattern. documentTool.ts's old single-tool id is fully retired.
• policy-review (exposed identifiers) , session instructions no longer echo the caller's literal userId/orgId.

What Greptile's review caught, verified and fixed (not just patched cosmetically):

• 4 mis-set tool annotations (document-write, ui-config, task under-claimed destructiveness; conversation-read under-claimed reaching an external CRM).
• Two truncation edge cases in buildSessionInstructions: an unbounded impersonated-user header that could exceed the 2KB budget with nothing to trim, and a UTF-16 surrogate-pair-splitting bug in the byte-truncation helper , both fixed with new regression tests that fail against the pre-fix logic.
• A real security-relevant approval-gate key that would have silently stopped working: document.share → document-write.share in HUMAN_ONLY_ACTIONS (matched via a literal ${toolId}.${action} string) , without the rename, autonomous callers could mint/revoke public document share links with zero human-in-the-loop gate.
• Several live model-facing prompts still calling the deleted document tool by name after the split , most seriously, workflows/chat/harness/subagents.ts's buildSubagentDefinitions() constructs the literal prompt handed to every configured chat subagent, telling it to load its own instructions via the now-nonexistent tool; every subagent delegation would have hit a tool-not-found error. Also fixed in draftCommsTool.ts and two skill markdown files.
• documentTool.schemas.ts added to the targetUserId-reaches-the-authority allowlist (a pure-schema file with no logic, split out of documentTool.ts purely for the 1,000-line budget , the real gating call is unchanged) , this was a CI failure, not a Greptile finding.
• A jose peer-dependency regression: apps/server pinned jose@6.0.11, one minor below @better-auth/core@1.6.33's ^6.1.0 peer requirement. Diffed against staging's lockfile and confirmed this exact resolution slot correctly resolved jose@6.2.12 there and regressed to 6.0.11 on this branch (a side effect of the earlier pnpm patch triggering re-resolution). Bumped to 6.1.3 (already used elsewhere in this lockfile) and regenerated , jose@6.0.11 no longer appears anywhere in pnpm-lock.yaml.

Test plan

• pnpm --filter @zero/server run types , clean
• pnpm deps:check , no dependency-direction violations
• Sco