feat: adopt Paperclip 2026.831 host surfaces (tool-access recipe, GITHUB_TOKEN exposure, boundary docs)

[alvarosanchez]

Implements the adoption items from the 2026.831 feature-fit analysis of GitHub Sync against Paperclip v2026.831.1.

What changed

1. Remove dead comment-annotation UI (439edfe)
The manifest stopped declaring the commentAnnotation slot when the host shipped its built-in GitHub external-object provider, so GitHubSyncCommentAnnotation, its data interface and the annotation-only styles were unreachable. The worker's comment.annotation data handler stays: it is still covered by tests and is the data source a host that renders the slot would read.

2. Tool-access profile recipe and detection (4c302ad)
The host MCP tool gateway is fail-closed. tool-access-policy.ts ends in deny_default when nothing matches, and plugin tool dispatch carries no connection/catalog/application id, so connection and catalog_entry profile selectors can never match a plugin tool (those selectors are validated to have a non-null id at write time). Only tool_name, risk_level or defaultAction: "allow" can grant them.

• README "Granting the tools to agents": the 21 qualified tool names, the exact 2026.831.1 request/response shapes, and a ready-to-run curl/jq script that derives the names from GET /api/plugins/tools?pluginId=paperclip-github-plugin, creates a defaultAction: "deny" profile with one tool_name include entry per tool, binds it at company scope, and verifies against one agent.
• Worker: settings.registration now returns a best-effort read-only agentToolAccess summary from GET /api/companies/{id}/tools/profiles/effective/agents/{agentId}, reporting toolsVisibleToAgents: number | null. Missing board access, missing agents, 403/404 and transport errors are reported as unavailable with a null count, never as an error. An allow-by-default (or risk_level) profile also reports null, because allowedToolNames only enumerates catalog-backed MCP tools and reporting zero there would be a false alarm. Cached two minutes per company.
• UI: warning banner in the GitHub access section when the count is a definite zero, linking to the README section.

3. GITHUB_TOKEN exposure (20f002f)
server/src/services/git-credentials.ts probes company secrets named GITHUB_TOKEN, GH_TOKEN, PAPERCLIP_GITHUB_TOKEN for managed-checkout git auth, the merged-PR confirmation sweep, the execution-workspace reaper and the built-in GitHub external-object provider. GitHub Sync stores github_sync_<companyId>, so those host features ran unauthenticated.

New default-off checkbox "Also expose this token to Paperclip as GITHUB_TOKEN" creates or rotates that company secret with the same value on save. Request building lives in the new src/ui/host-secrets.ts so it is unit-testable. The host matches names with plain SQL equality, so the host secret is matched case-sensitively and a name/key conflict is surfaced with an actionable message rather than rotating the wrong row. A failure there never fails the token save.

4. Compatibility-boundary docs (deba72f)
Company export/import bundles have no plugin section at all, so mappings, plugin config, link entities, the import registry, KPI history and the interaction ledger do not survive an import (re-link action is future work). The experimental Connections v3 GitHub app is raw GitHub MCP tooling, whereas GitHub Sync tools are issue-aware, ledger-recorded and never expose the token. The host's merged-PR confirmation sweep is read-only and coexists with plugin status routing.

5. Tests (9367708)
12 new tests: six for the agentToolAccess worker data path, six for src/ui/host-secrets.ts.

Notes

• The task description mentioned a selectorValue field on profile entries. There is no such field at v2026.831.1; the validator takes selectorType, effect, toolName, riskLevel, applicationId, connectionId, catalogEntryId, conditions, and silently drops unknown keys. The README documents the real shape.
• SPEC.md gained matching requirements for the tool-access recipe, the agentToolAccess summary, the opt-in host secret, and the portability/coexistence boundaries.
• No version bump, no release.

Verification

pnpm typecheck, pnpm test (350 pass, 0 fail) and pnpm build are green locally. pnpm test:e2e runs on merged main.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Six unresolved moderate findings affect tool-access reporting, host-secret handling, company switching, and setup-script error handling.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adopts Paperclip 2026.831 host integrations for GitHub Sync, including tool access, optional GITHUB_TOKEN exposure, and compatibility documentation.

Changes:

• Adds tool-access detection, warnings, and setup guidance.
• Adds opt-in host-secret token exposure.
• Removes obsolete annotation UI and updates specifications, tests, and boundary documentation.

File summaries

File	Summary	Final findings
tests/plugin.spec.ts	Adds worker and host-secret helper tests.	No final comments.
src/worker.ts	Adds cached agent tool-access probing.	Moderate (2 votes): Sampling agents can misrepresent agent-scoped policies; evaluate relevant agents or label the result as a sample.
src/ui/index.tsx	Adds token exposure control and access warnings.	Moderate (1 vote): The warning may incorrectly claim company-wide denial when agent-scoped bindings differ. Moderate (1 vote): Reset or key the exposure opt-in when switching companies.
src/ui/host-secrets.ts	Implements host-secret creation and rotation helpers.	Moderate (3 votes): Trimming stored names conflicts with exact host matching. Moderate (1 vote): Inactive or archived secrets may be rotated without becoming usable.
SPEC.md	Adds requirements for host integrations and compatibility boundaries.	No final comments.
README.md	Documents tool grants, token exposure, and compatibility.	Moderate (2 votes): The setup script should fail on HTTP errors before consuming returned IDs.

Review details

Suppressed comments (3)

src/ui/host-secrets.ts:104

• This path rotates any matching row without checking its status. If an existing GITHUB_TOKEN secret is disabled or archived, the documented host credential resolver skips it, so the checkbox can report success while Paperclip's host features remain unauthenticated. Include the status in the list result and reject or explicitly reactivate inactive rows before claiming exposure succeeded.

  if (existing) {
    const rotateRequest = buildCompanySecretRotateRequest(existing.id, value);
    return fetchJson<CompanySecretSummary>(rotateRequest.url, rotateRequest.init);

src/ui/index.tsx:12711

• The probe requests effective profiles for only the first active/checkable agent, but this copy claims that no profile in the company includes the tools and that all agents will be denied. An agent-scoped binding for another agent can coexist with a zero result here (the README documents that agent bindings override company bindings), so the warning becomes false; either check all relevant agents or scope the summary and copy to checkedAgentId.

                      {`Paperclip's tool gateway is fail-closed, and no tool profile in this company includes any of the `}
                      {agentToolAccess?.totalToolCount ? `${agentToolAccess.totalToolCount} ` : ''}
                      {`${GITHUB_SYNC_PLUGIN_ID}:* tools, so agents will not be offered them. `}
                      {'Bind a tool profile with tool_name include entries for this company.'}

src/ui/index.tsx:11251

• This opt-in flag is not reset when settings.data changes. Because the settings component survives company switches, a user can check it for company A, switch to company B, and then save B's token with host-secret exposure still enabled even though they never opted in for B. Reset it on company/settings transitions (or key the state by company) before allowing the next save.

  const [exposeTokenAsHostSecret, setExposeTokenAsHostSecret] = useState(false);

• Files reviewed: 6/6 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[alvarosanchez]

All six Copilot findings are addressed in 1988fa2. The three inline threads have replies and are resolved; the three that only appeared in the file-summary table:

• src/ui/index.tsx — warning may claim company-wide denial. Same root cause as the worker finding: the banner is now titled after the sampled agent and states that it is a sample of one agent of N, and that an agent-scoped binding overrides the company one.
• src/ui/index.tsx — reset or key the exposure opt-in when switching companies. exposeTokenAsHostSecret now resets in a useEffect keyed on hostContext.companyId, in addition to the existing resets on save and cancel.
• src/ui/host-secrets.ts — inactive or archived secrets may be rotated. exposeGitHubTokenToPaperclipHost now reads the secret's status and refuses with an actionable message when it is not active, instead of issuing a rotate that the host answers with 422 and that the git-credential probe would skip anyway. Covered by a new test.

pnpm typecheck, pnpm test (351 pass) and pnpm build are green.