fix: admit documented sandbox task context routes (#16892)

## Thinking Path

> - Paperclip agents use task context to complete assigned work.
> - Sandboxed agents reach the controller through a bounded callback
bridge.
> - The bridge rejects several documented context routes before
controller authorization runs.
> - An authorized agent cannot read a task screenshot or referenced
skill file, or inspect a missed monitor wake.
> - This pull request admits only the exact context routes and supported
methods.
> - The controller continues to enforce company, resource, task and
monitor authority.

## Linked Issues or Issue Description

**What happened?**

Both callback transports return `Route not allowed` for task asset
content, company skill detail and files, wake diagnostics, and the
monitor check-now action. These operations already exist in the
controller.

**Expected behavior**

A sandboxed agent can use these documented operations when the
controller authorizes its request. Other methods, deeper paths, skill
mutations, and recovery resolution remain restricted.

**Steps to reproduce**

Use a sandbox callback to read an asset URL from a task description,
read a company skill's referenced file, or inspect a task's wake
diagnostics. The baseline bridge rejects each request. The new
regression matrix runs all five operations against both transport
allowlists.

Related: #16772 documents refused callback routes. This PR fixes the
context routes listed above; it does not add company-wide activity or
labels access.

## What Changed

- Admit asset content, skill detail/files, and wake diagnostic reads.
- Admit the existing monitor check-now action with controller
authorization.
- Add a focused allow/deny matrix for both transports.
- Update the operational API reference and access maps.

## Verification

- With the pre-fix bridge rules, all 10 allowed-request cases fail with
`Route not allowed` across the two transports; all 24 deny controls
still pass.
- With the fix restored, all 34 route cases pass. The matrix plus
existing callback suite passes 119 tests across two files.
- Local `pnpm -r typecheck` and `pnpm build` pass.
- The access-map checker, capability contract generation check, and
capability inventory check pass.
- Full repository CI passes on `97f9f06b2c`: typecheck/release registry,
all test shards, build, Docker context, canary dry run, and aggregate
verify.
- The duplicate local full-suite run was stopped after 24 minutes once
full CI passed; it is not claimed as a completed local pass.
- Greptile is 5/5 on the current head with no inline findings.
Independent source review checked asset, skill, wake-diagnostic, and
monitor controller authorization and found no actionable issues.
- The secondary Paperclip automated review is neutral/incomplete.
Independent review covered its missing controller checks; the real
Vitest cases and full CI provide execution evidence.

## Risks

This widens transport admission for five existing operations. It does
not change controller authorization. Asset reads still check
company/task visibility; skill reads keep source policy; monitor checks
keep ownership and management permission. No schema or UI change is
required.

## Model Used

OpenAI Codex, GPT-6 family, with tool use and code execution. The
session does not expose the exact serving model ID or context window.
The work used failing-before and passing-after regression tests.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

maps/agent-access-map/documents-artifacts.md

@@ -85,6 +85,10 @@ credentials/run context; inspect its result and applicable persistence/attributi
 Assert the relevant denied actor, owner, company or mode from Policy. Review the
 remaining operations before qualifying the whole capability.
 
+Queue and HTTP/2 sandbox callbacks admit `GET /api/assets/{assetId}/content`,
+including screenshot references in task descriptions. The controller still checks
+company and task visibility before opening storage.
+
 Gaps: Native API uploads are bounded; attachment reading has target/provider and
 permission conditions.
 

maps/agent-access-map/skills.md

@@ -20,7 +20,10 @@ API: `present` — representative operation IDs:
 - `GET /api/companies/{companyId}/skills`.
 - `POST /api/companies/{companyId}/skills/import`.
 
-Agent access: `available` — REST / native call_api / CLI skills and sources.
+Agent access: `available` — REST / native call_api / CLI skills and sources. Queue
+and HTTP/2 sandbox callbacks also admit company skill detail and file reads;
+file paths travel in the existing `path` query parameter. Skill mutations stay
+subject to the existing bridge restrictions.
 
 Policy: Company skill policy by action/resource plus platform invariants; test execution
 additionally requires task-assignment authority.

maps/agent-access-map/tasks.md

@@ -120,6 +120,11 @@ regressions in [ownership tests](../../server/src/__tests__/issue-agent-mutation
 cover a human handoff and stop enforcement for other actors, runtimes and targets;
 they use mocked services and do not claim live execution proof.
 
+Queue and HTTP/2 sandbox callbacks admit `GET /api/issues/{id}/diagnostics/wakes`
+and `POST /api/issues/{id}/monitor/check-now`. The controller still checks task
+read access or monitor-management permission and assignment ownership. Recovery
+resolution and scheduled-retry controls remain outside this bridge surface.
+
 Monitor verification: submit flat scheduling fields, observe the schema rejection
 and unchanged task, then retry with the nested `monitor` object and the same
 idempotency key. Inspect the saved schedule and audit, yield, and verify exactly

packages/adapter-utils/src/sandbox-callback-bridge.ts

@@ -151,6 +151,8 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa
   { method: "GET", path: /^\/api\/companies\/[^/]+\/approvals$/ },
   { method: "GET", path: /^\/api\/companies\/[^/]+\/routines$/ },
   { method: "GET", path: /^\/api\/companies\/[^/]+\/skills$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/skills\/[^/]+$/ },
+  { method: "GET", path: /^\/api\/companies\/[^/]+\/skills\/[^/]+\/files$/ },
   { method: "GET", path: /^\/api\/projects\/[^/]+$/ },
   { method: "GET", path: /^\/api\/goals\/[^/]+$/ },
 
@@ -170,6 +172,8 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa
   // Issue lifecycle: read context, checkout, update, comment, document, release
   { method: "GET", path: /^\/api\/issues\/[^/]+$/ },
   { method: "GET", path: /^\/api\/issues\/[^/]+\/heartbeat-context$/ },
+  { method: "GET", path: /^\/api\/issues\/[^/]+\/diagnostics\/wakes$/ },
+  { method: "POST", path: /^\/api\/issues\/[^/]+\/monitor\/check-now$/ },
   // The controller still checks company membership and issue read authority.
   { method: "GET", path: /^\/api\/issues\/[^/]+\/activity$/ },
   { method: "GET", path: /^\/api\/issues\/[^/]+\/comments(?:\/[^/]+)?$/ },
@@ -186,6 +190,7 @@ export const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCa
   { method: "GET", path: /^\/api\/issues\/[^/]+\/attachments$/ },
   { method: "POST", path: /^\/api\/companies\/[^/]+\/issues\/[^/]+\/attachments$/ },
   { method: "GET", path: /^\/api\/attachments\/[^/]+\/content$/ },
+  { method: "GET", path: /^\/api\/assets\/[^/]+\/content$/ },
 
   // Work products: publish branch/commit/artifact metadata for completed work.
   { method: "GET", path: /^\/api\/issues\/[^/]+\/work-products$/ },

packages/adapter-utils/src/sandbox-callback-context-routes.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import {
+  authorizeSandboxCallbackBridgeRequestWithRoutes,
+  HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST,
+} from "./sandbox-callback-bridge.js";
+
+const contextRequests = [
+  { method: "GET", path: "/api/assets/screenshot-1/content" },
+  { method: "GET", path: "/api/companies/company-1/skills/skill-1" },
+  { method: "GET", path: "/api/companies/company-1/skills/skill-1/files", query: "?path=references%2Fworkflow.md" },
+  { method: "GET", path: "/api/issues/task-1/diagnostics/wakes" },
+  { method: "POST", path: "/api/issues/task-1/monitor/check-now" },
+];
+
+const deniedRequests = [
+  { method: "POST", path: "/api/assets/screenshot-1/content" },
+  { method: "DELETE", path: "/api/assets/screenshot-1/content" },
+  { method: "GET", path: "/api/assets/screenshot-1/content/extra" },
+  { method: "PATCH", path: "/api/companies/company-1/skills/skill-1" },
+  { method: "PATCH", path: "/api/companies/company-1/skills/skill-1/files" },
+  { method: "DELETE", path: "/api/companies/company-1/skills/skill-1/files" },
+  { method: "GET", path: "/api/companies/company-1/skills/skill-1/files/extra" },
+  { method: "POST", path: "/api/issues/task-1/diagnostics/wakes" },
+  { method: "GET", path: "/api/issues/task-1/diagnostics/wakes/extra" },
+  { method: "GET", path: "/api/issues/task-1/monitor/check-now" },
+  { method: "POST", path: "/api/issues/task-1/monitor/check-now/extra" },
+  { method: "POST", path: "/api/issues/task-1/recovery-actions/resolve" },
+];
+
+describe.each([
+  ["queue", undefined],
+  ["HTTP/2", HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST],
+] as const)("sandbox task context over %s", (_transport, routes) => {
+  it.each(contextRequests)("admits documented context request $method $path", request => {
+    expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request, routes)).toBeNull();
+  });
+
+  it.each(deniedRequests)("keeps unrelated operations denied: $method $path", request => {
+    expect(authorizeSandboxCallbackBridgeRequestWithRoutes(request, routes))
+      .toBe(`Route not allowed: ${request.method} ${request.path}`);
+  });
+});

skills/paperclip/references/api-reference.md

@@ -1699,3 +1699,15 @@ identity, or a closed task receive 409; unrelated connections receive 404.
 No credentials or provider authorization URL appear in the card payload.
 
 For sandbox run inspection, see [Run diagnostics from a sandbox](run-diagnostics.md).
+
+**Sandbox task context routes.**
+
+The queue and HTTP/2 callback bridges admit company skill detail and file reads,
+`GET /api/assets/{assetId}/content`, `GET /api/issues/{id}/diagnostics/wakes`,
+and `POST /api/issues/{id}/monitor/check-now`. Use the asset URL embedded in the
+task to read its screenshot. Use the skill files route with a `path` query
+parameter to read a referenced script or instruction file.
+
+Bridge admission does not grant resource access. The controller rechecks company,
+task and skill visibility, and monitor-management permission. Asset mutations,
+skill-file mutations and recovery-action resolution remain restricted.