papercliped 2.3.0 → 2.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## v2.4.0 — the control room: manage every session, agent and tool inside Paperclip
+
+- **The control room.** The Papercliped plugin now opens a control room inside Paperclip, in Paperclip's own design: a left menu that replaces the company menu (Overview, Sessions, Agents, Tools, Activity, Settings), the way Paperclip's own agent page does. See every connected AI app, what each may use, which agents it applies to, and what it has done. New guides: **The control room** and **API only, Full or Agent only**.
+- **An access switch: API only, Full or Agent only.** One three-position switch (with a sliding knob, keyboard support and a small version for the dashboard) decides how AI apps may work with your Paperclip. **API only**: look and control Paperclip directly (pause, budgets, approvals, goals) but don't hand work to agents. **Agent only**: look and work through agents (create, assign and comment on issues, wake an agent) but no direct control. **Full** (the default, so nothing changes until you choose): both. It takes effect on the app's next request.
+- **Set any agent apart.** On the Agents page, or on a new **Papercliped tab on every agent's page**, give an agent its own mode, or turn it **Off**: AI apps can't see it, touch it, or see what is assigned to it. Off agents are removed from lists and reports before the report is written, so they can't leak into a summary.
+- **Sessions you can manage.** Every connected app is a session: give it a name, change its level, choose exactly which of the tools it may use (grouped as Look, Work through agents and Direct control), and choose whether it applies to everyone or only selected agents. A session limited to selected agents works only with those agents; it can't use views across every agent, and the page says so.
+- **Blocked calls are visible.** A refused call returns a plain message naming the setting and where to change it (with a `policy` code in the API), and shows as **Blocked** in the new Activity page, which lists the newest calls, their session, tool and result, never what was sent or returned. AI apps are no longer shown tools that can never run for their session.
+- **A dashboard widget** with the access switch in small, the number of sessions and how many calls were blocked today.
+- **Tool reference shows each tool's kind** (a new "Works in" column), and `paperclip_api_request` is described correctly: `GET` works in every mode.
+- **For API users:** new management endpoints `GET /sessions`, `POST|DELETE /sessions/:id`, `GET|POST|PUT /policy`, `GET /tools` and `GET /activity`; a new error class `policy_blocked` in the public API's aggregate error classes; migration `007_control_room.sql` adds two nullable columns and needs no backfill.
+- **Update note.** Paperclip won't update a plugin to a version that asks for new permissions without an admin's approval, so to get the control room remove the Papercliped plugin in Settings → Plugins and install it again (or connect your Paperclip again with the install box ticked). Your account, sessions and settings are kept.
+- **The Papercliped plugin now looks like part of Paperclip.** Its sidebar entry has the same paperclip icon, spacing, type, hover and highlighted-when-open look as Tasks, Artifacts and Cases, and the page uses Paperclip’s own cards, inputs, buttons, tabs and text styles, so it follows your theme (light, dark, seasonal) instead of imitating it.
+- **Fixed: the Papercliped page inside Paperclip no longer invites your browser to fill in your Paperclip login.** The page shares an address with Paperclip’s own sign-in, so browsers offered your saved Paperclip email and password in the "Link your Papercliped account" fields, one click from sending that password to Papercliped as a "secret key". Those fields (and the confirm boxes) now tell the browser not to autofill. If you linked an account on 2.2.1, nothing needs doing; if a saved login was ever filled in, do not press Link.
+
 ## v2.3.0 — host your Paperclip anywhere, and a prompt gallery
 
 - **Host your Paperclip: a step-by-step guide for every option.** A new docs section takes you from nothing to a running Paperclip with a public `https://` address, connected to Papercliped and answering your first prompt. It covers your own computer with a free tunnel (Cloudflare Tunnel, Tailscale Funnel, ngrok), a VPS with Docker and Caddy (Hetzner, DigitalOcean, Linode, Oracle's free tier), Railway, Render, Fly.io and Coolify, with a comparison of cost and effort. Every guide uses the official Paperclip image and the settings current Paperclip needs: authenticated mode with public exposure, your public URL, the two secrets, a persistent disk at `/paperclip`, creating the first admin with `paperclipai auth bootstrap-ceo`, and signing in your agents with API keys or a subscription. They also cover updates and backups. Hosts that sleep or have no disk are flagged as unsuitable.

package/README.md

@@ -92,7 +92,7 @@ There are 30 tools ([full list](https://docs.papercliped.co/tools)). **Read only
 
 ## Manage your connections in Paperclip
 
-Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a Papercliped page where you see every connected app, switch its level, disconnect it, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin).
+Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a **control room**: see every connected app, choose which tools each may use and which agents it applies to, set **API only / Full / Agent only** for every agent or one at a time (or turn an agent off), read what was blocked, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin) · [The control room](https://docs.papercliped.co/control-room) · [API only, Full or Agent only](https://docs.papercliped.co/access-modes).
 
 ## Security and privacy
 

package/dist/access/guard.js

@@ -0,0 +1,17 @@
+import { redactAgents } from "./policy.js";
+/**
+ * A view of the user's Paperclip in which some agents do not exist. Every response is stripped of those agents before a tool
+ * sees it, so reports, lists and syncs are all consistent: a report built from this client cannot name a hidden agent,
+ * because it never received one. Anything the server already summed (totals) is left as it is.
+ */
+export function guardClient(client, hidden) {
+    if (hidden.size === 0)
+        return client;
+    const g = Object.create(client);
+    const request = async (...args) => redactAgents(await client.request(...args), hidden);
+    g.request = request;
+    g.get = ((path, query) => request("GET", path, { query }));
+    g.post = ((path, body) => request("POST", path, { body: body ?? {} }));
+    g.patch = ((path, body) => request("PATCH", path, { body }));
+    return g;
+}

package/dist/access/policy.js

@@ -0,0 +1,203 @@
+export const MODES = ["api", "full", "agent"];
+export const isMode = (v) => typeof v === "string" && MODES.includes(v);
+export const isAgentMode = (v) => v === "off" || isMode(v);
+export const DEFAULT_ACCOUNT_POLICY = { mode: "full", agents: {} };
+export const DEFAULT_SESSION_POLICY = { label: null, tools: null, agents: null };
+/** Hands work to an agent. Everything else that changes something is direct control of Paperclip. */
+const AGENT_WORK = new Set(["paperclip_create_issue", "paperclip_update_issue", "paperclip_comment_issue", "paperclip_wake_agent"]);
+/** Which surface a call is on. The raw API tool is read for GET and direct control for anything else. */
+export function surfaceOf(tool, input = {}) {
+    if (tool.name === "paperclip_api_request")
+        return input.method === "GET" ? "read" : "api";
+    if (tool.access === "read")
+        return "read";
+    return AGENT_WORK.has(tool.name) ? "agent" : "api";
+}
+/** The surface a tool is on when called in its usual way (what the control room shows). */
+export const surfaceOfTool = (tool) => surfaceOf(tool, {});
+export const surfaceAllowed = (mode, surface) => surface === "read" || mode === "full" || (mode === "api" && surface === "api") || (mode === "agent" && surface === "agent");
+export const MODE_LABEL = { api: "API only", full: "Full", agent: "Agent only", off: "Off" };
+// ───────────── validation of what the manage API receives ─────────────
+export class PolicyInputError extends Error {
+}
+const ID = /^[A-Za-z0-9._:-]{1,80}$/;
+const MAX_AGENTS = 500;
+/** A strict, bounded copy of untrusted input. Unknown keys are dropped; anything invalid is refused. */
+export function parseAccountPolicy(raw) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    const mode = o.mode === undefined ? DEFAULT_ACCOUNT_POLICY.mode : o.mode;
+    if (!isMode(mode))
+        throw new PolicyInputError("mode must be api, full or agent");
+    const agents = {};
+    const src = o.agents === undefined ? {} : o.agents;
+    if (!src || typeof src !== "object" || Array.isArray(src))
+        throw new PolicyInputError("agents must be an object of agent id to mode");
+    const entries = Object.entries(src);
+    if (entries.length > MAX_AGENTS)
+        throw new PolicyInputError(`at most ${MAX_AGENTS} agents`);
+    for (const [id, m] of entries) {
+        if (!ID.test(id))
+            throw new PolicyInputError("invalid agent id");
+        if (!isAgentMode(m))
+            throw new PolicyInputError("an agent's mode must be api, full, agent or off");
+        if (m !== mode)
+            agents[id] = m; // an override equal to the default is no override
+    }
+    return { mode, agents };
+}
+export function parseSessionPolicy(raw, knownTools) {
+    const o = (raw && typeof raw === "object" ? raw : {});
+    let label = null;
+    if (o.label !== undefined && o.label !== null) {
+        if (typeof o.label !== "string")
+            throw new PolicyInputError("label must be text");
+        label = o.label.replace(/\s+/g, " ").trim().slice(0, 60) || null;
+    }
+    const list = (v, what, ok) => {
+        if (v === undefined || v === null)
+            return null;
+        if (!Array.isArray(v))
+            throw new PolicyInputError(`${what} must be a list, or null for all`);
+        if (v.length > MAX_AGENTS)
+            throw new PolicyInputError(`too many ${what}`);
+        const out = [...new Set(v.map(String))];
+        if (!out.every(ok))
+            throw new PolicyInputError(`invalid entry in ${what}`);
+        return out;
+    };
+    const tools = list(o.tools, "tools", (s) => knownTools.has(s));
+    const agents = list(o.agents, "agents", (s) => ID.test(s));
+    if (tools && tools.length === 0)
+        throw new PolicyInputError("choose at least one tool, or allow all");
+    if (agents && agents.length === 0)
+        throw new PolicyInputError("choose at least one agent, or apply to everyone");
+    return { label, tools, agents };
+}
+/** Stored JSON back to a policy, tolerating older or damaged rows by falling back to the safe default. */
+export function readAccountPolicy(stored) {
+    try {
+        return parseAccountPolicy(typeof stored === "string" ? JSON.parse(stored) : stored);
+    }
+    catch {
+        return { ...DEFAULT_ACCOUNT_POLICY, agents: {} };
+    }
+}
+export function readSessionPolicy(stored, knownTools) {
+    if (stored === null || stored === undefined)
+        return { ...DEFAULT_SESSION_POLICY };
+    try {
+        return parseSessionPolicy(typeof stored === "string" ? JSON.parse(stored) : stored, knownTools);
+    }
+    catch {
+        return { ...DEFAULT_SESSION_POLICY };
+    }
+}
+const CONTROL_ROOM = "Change it in the Papercliped page inside Paperclip.";
+/** Agent ids a call names, wherever the tool takes them (a target, an assignee, an owner, or a filter). */
+export function targetsOf(input) {
+    const ids = [input.agentId, input.assigneeAgentId, input.ownerAgentId].filter((v) => typeof v === "string" && v.trim().length > 0);
+    return [...new Set(ids.map((s) => s.trim()))];
+}
+/** Tools that act on an issue, whose agent is whoever it is assigned to (not named in the call). */
+const BY_ISSUE = new Set(["paperclip_get_issue", "paperclip_update_issue", "paperclip_comment_issue"]);
+/** Tools a session limited to selected agents may still use without naming an agent. */
+const OPEN_TO_LIMITED = new Set(["papercliped_service_status", "paperclip_list_companies", "paperclip_list_agents"]);
+/** Does this call need the issue's current assignee looked up before it can be judged? */
+export function needsIssueAgent(p, tool) {
+    return BY_ISSUE.has(tool.name) && (p.session.agents !== null || Object.keys(p.account.agents).length > 0);
+}
+/** Agents Papercliped may not touch at all: hidden from every result, refused as a target. */
+export const hiddenAgents = (a) => Object.entries(a.agents).filter(([, m]) => m === "off").map(([id]) => id);
+/**
+ * Decide one call. `issueAgent` is the assignee of the issue the call names (null = unassigned, undefined = not looked up).
+ * Returns null when the call may go ahead, or why not.
+ */
+export function evaluate(p, tool, input, issueAgent) {
+    const { account, session } = p;
+    const label = tool.title || tool.name;
+    if (session.tools && !session.tools.includes(tool.name)) {
+        return { code: "tool_not_allowed", message: `This session isn't allowed to use "${label}". ${CONTROL_ROOM}` };
+    }
+    const surface = surfaceOf(tool, input);
+    const targets = targetsOf(input);
+    if (typeof issueAgent === "string")
+        targets.push(issueAgent);
+    for (const a of new Set(targets)) {
+        const eff = account.agents[a] ?? account.mode;
+        if (eff === "off")
+            return { code: "agent_off", message: `Papercliped isn't allowed to use that agent. ${CONTROL_ROOM}` };
+        if (!surfaceAllowed(eff, surface))
+            return { code: "mode_blocks", message: `That agent is set to "${MODE_LABEL[eff]}", which doesn't allow "${label}". ${CONTROL_ROOM}` };
+        if (session.agents && !session.agents.includes(a))
+            return { code: "agent_not_in_session", message: `This session only applies to selected agents, and that one isn't included. ${CONTROL_ROOM}` };
+    }
+    if (targets.length === 0 && !surfaceAllowed(account.mode, surface)) {
+        return { code: "mode_blocks", message: `Papercliped is set to "${MODE_LABEL[account.mode]}", which doesn't allow "${label}". ${CONTROL_ROOM}` };
+    }
+    if (session.agents && targets.length === 0 && !OPEN_TO_LIMITED.has(tool.name)) {
+        const why = BY_ISSUE.has(tool.name) || tool.name === "paperclip_create_issue" ? "needs an issue assigned to one of its agents" : "looks across every agent";
+        return { code: "needs_all_agents", message: `This session only applies to selected agents, and "${label}" ${why}. ${CONTROL_ROOM}` };
+    }
+    return null;
+}
+/** For a session limited to selected agents: the agent list shows only those. */
+export function narrowAgentList(result, allowed) {
+    const keep = (x) => !!x && typeof x === "object" && allowed.includes(String(x.id));
+    if (Array.isArray(result))
+        return result.filter(keep);
+    if (result && typeof result === "object" && Array.isArray(result.agents)) {
+        return { ...result, agents: result.agents.filter(keep) };
+    }
+    return result;
+}
+const AGENT_REFS = ["id", "agentId", "assigneeAgentId", "ownerAgentId", "executorAgentId", "createdByAgentId"];
+/**
+ * Remove every record that belongs to one of the hidden agents, wherever it appears in a response: list items, nested
+ * rows, and keys named by agent id. Totals the server already summed are left as they are.
+ */
+export function redactAgents(value, hidden) {
+    if (hidden.size === 0)
+        return value;
+    const belongs = (x) => {
+        if (!x || typeof x !== "object")
+            return false;
+        const o = x;
+        return AGENT_REFS.some((k) => typeof o[k] === "string" && hidden.has(o[k]));
+    };
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.filter((x) => !belongs(x)).map(walk);
+        if (v && typeof v === "object") {
+            const out = {};
+            for (const [k, x] of Object.entries(v)) {
+                if (hidden.has(k) || belongs(x))
+                    continue;
+                out[k] = walk(x);
+            }
+            return out;
+        }
+        return v;
+    };
+    return walk(value);
+}
+const takesAgent = (tool) => {
+    const shape = tool.schema.shape ?? {};
+    return "agentId" in shape || "assigneeAgentId" in shape || "ownerAgentId" in shape;
+};
+/**
+ * Could this tool ever run for this session? A tool that can never run is not advertised to the AI, so it doesn't try it.
+ * (Whether a particular call may run is `evaluate`'s answer.)
+ */
+export function canEverRun(p, tool) {
+    if (p.session.tools && !p.session.tools.includes(tool.name))
+        return false;
+    if (tool.name !== "paperclip_api_request") {
+        const surface = surfaceOfTool(tool);
+        const modes = [p.account.mode, ...Object.values(p.account.agents).filter((m) => m !== "off")];
+        if (!modes.some((m) => surfaceAllowed(m, surface)))
+            return false;
+    }
+    if (p.session.agents)
+        return OPEN_TO_LIMITED.has(tool.name) || BY_ISSUE.has(tool.name) || tool.name === "paperclip_create_issue" || takesAgent(tool);
+    return true;
+}

package/dist/execute.js

@@ -1,3 +1,5 @@
+import { guardClient } from "./access/guard.js";
+import { evaluate, hiddenAgents, narrowAgentList, needsIssueAgent } from "./access/policy.js";
 import { PaperclipApiError } from "./client.js";
 import { ToolInputError } from "./errors.js";
 import { requiredScope, scopeAllows } from "./oauth/scopes.js";
@@ -53,8 +55,30 @@ export async function executeTool(client, name, rawInput, opts = {}) {
     if (client.config.readOnly && mutation) {
         return done({ ok: false, status: 403, error: "Bridge is in read-only mode (PAPERCLIP_READ_ONLY); this action was not sent to Paperclip." }, "read_only");
     }
+    let runWith = client;
+    const policy = opts.policy;
+    if (policy) {
+        // An issue's agent is whoever it is assigned to; look it up once, only when the answer can change the decision.
+        let issueAgent;
+        if (needsIssueAgent(policy, tool) && typeof parsed.data.issueId === "string") {
+            try {
+                const issue = await client.get(`/issues/${encodeURIComponent(parsed.data.issueId)}`);
+                issueAgent = typeof issue?.assigneeAgentId === "string" ? issue.assigneeAgentId : null;
+            }
+            catch {
+                issueAgent = undefined; // can't tell: a session limited to selected agents is refused below, anything else lets the tool report the real error
+            }
+        }
+        const denial = evaluate(policy, tool, parsed.data, issueAgent);
+        if (denial)
+            return done({ ok: false, status: 403, error: { message: denial.message, policy: denial.code } }, "policy_blocked");
+        runWith = guardClient(client, new Set(hiddenAgents(policy.account)));
+    }
     try {
-        return done({ ok: true, result: await runTimed(timer, () => tool.run(client, parsed.data)) });
+        let result = await runTimed(timer, () => tool.run(runWith, parsed.data));
+        if (policy?.session.agents && tool.name === "paperclip_list_agents")
+            result = narrowAgentList(result, policy.session.agents);
+        return done({ ok: true, result });
     }
     catch (err) {
         if (err instanceof ToolInputError)

package/dist/manage/routes.js

@@ -1,3 +1,4 @@
+import { PolicyInputError } from "../access/policy.js";
 import { displayName } from "../accounts/alias.js";
 const HEADERS = { "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer" };
 /** A DNS name or IPv4 literal, optionally with a port; undefined when it is anything else. */
@@ -92,8 +93,51 @@ export class ManageRoutes {
             const link = await this.p.manageInstanceLabel(a.id);
             return this.json(res, 200, { name: displayName(a), anonymous: !!a.anonymous, alias: a.alias ?? null, paperclip: link.label, connected: link.connected, createdAt: a.createdAt });
         }
-        if (m === "GET" && route === "/connections")
-            return this.json(res, 200, { connections: await this.p.manageConnections(a.id) });
+        if (m === "GET" && (route === "/connections" || route === "/sessions")) {
+            const list = await this.p.manageConnections(a.id);
+            return this.json(res, 200, route === "/sessions" ? { sessions: list } : { connections: list });
+        }
+        // The control room: the access switch, per-session limits, the tool list and recent calls.
+        if (route === "/policy" && (m === "GET" || m === "POST" || m === "PUT")) {
+            if (m === "GET")
+                return this.json(res, 200, await this.p.manageGetPolicy(a));
+            const b = await this.body(req);
+            if (!b)
+                return this.json(res, 400, { error: "Send JSON" });
+            try {
+                return this.json(res, 200, await this.p.manageSetPolicy(a, b));
+            }
+            catch (e) {
+                return e instanceof PolicyInputError ? this.json(res, 400, { error: e.message }) : this.json(res, 500, { error: "Could not save the access settings" });
+            }
+        }
+        if (m === "GET" && route === "/tools")
+            return this.json(res, 200, { tools: this.p.manageTools() });
+        if (m === "GET" && route === "/activity") {
+            const session = url.searchParams.get("session") ?? undefined;
+            if (session !== undefined && !/^[A-Za-z0-9_-]{1,80}$/.test(session))
+                return this.json(res, 400, { error: "Invalid session" });
+            const limit = Number.parseInt(url.searchParams.get("limit") ?? "50", 10);
+            return this.json(res, 200, { calls: await this.p.manageActivity(a, { session, limit: Number.isFinite(limit) ? limit : 50 }) });
+        }
+        const sess = /^\/sessions\/([A-Za-z0-9_-]{1,80})$/.exec(route);
+        if (sess && m === "POST") {
+            const b = await this.body(req);
+            if (!b)
+                return this.json(res, 400, { error: "Send JSON" });
+            const level = b.level === undefined ? undefined : b.level === "read" ? "paperclip:read" : b.level === "control" ? "paperclip:control" : null;
+            if (level === null)
+                return this.json(res, 400, { error: "level must be read or control" });
+            try {
+                const next = await this.p.manageSetSession(a, sess[1], { label: b.label, tools: b.tools, agents: b.agents, level });
+                return next ? this.json(res, 200, next) : this.json(res, 404, { error: "No such session" });
+            }
+            catch (e) {
+                return e instanceof PolicyInputError ? this.json(res, 400, { error: e.message }) : this.json(res, 500, { error: "Could not save the session" });
+            }
+        }
+        if (sess && m === "DELETE")
+            return (await this.p.manageRevoke(a, sess[1])) ? this.json(res, 200, { ok: true }) : this.json(res, 404, { error: "No such session" });
         const c = /^\/connections\/([A-Za-z0-9_-]{1,80})$/.exec(route);
         if (c && m === "POST") {
             const b = await this.body(req);

package/dist/mcp.js

@@ -2,19 +2,20 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { PaperclipClient } from "./client.js";
 import { readConfig } from "./config.js";
 import { executeTool, renderForModel } from "./execute.js";
+import { canEverRun } from "./access/policy.js";
 import { requiredScope, scopeAllows } from "./oauth/scopes.js";
 import { tools } from "./tools.js";
 export { VERSION as SERVER_VERSION } from "./version.js";
 import { VERSION } from "./version.js";
 /** Tools above the caller's scope are not advertised (they would only fail). The raw API tool stays: its GETs need only read. */
-export function visibleTools(scopes) {
-    if (!scopes)
-        return tools;
-    return tools.filter((t) => t.name === "paperclip_api_request" || scopeAllows(scopes, requiredScope(t)));
+export function visibleTools(scopes, policy) {
+    const byScope = !scopes ? tools : tools.filter((t) => t.name === "paperclip_api_request" || scopeAllows(scopes, requiredScope(t)));
+    // Tools the session or the account switch can never allow are not advertised either.
+    return policy ? byScope.filter((t) => canEverRun(policy, t)) : byScope;
 }
 export function createMcpServer(config = readConfig(), client = new PaperclipClient(config), exec = {}) {
     const server = new McpServer({ name: "papercliped", version: VERSION });
-    for (const tool of visibleTools(exec.scopes)) {
+    for (const tool of visibleTools(exec.scopes, exec.policy)) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,

package/dist/oauth/pg-store.js

@@ -28,6 +28,7 @@ const toGrant = (r) => ({
     createdAt: num(r.created_at),
     lastUsedAt: num(r.last_used_at),
     revoked: r.revoked,
+    policy: r.policy ?? null,
 });
 /**
  * Postgres-backed Store (schema `bridge`, see migrations/001_init.sql). Safe to share between several bridge
@@ -174,7 +175,7 @@ export class PgStore {
     }
     // ───────────── accounts ─────────────
     static toAccount(x) {
-        return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta };
+        return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta, policy: x.policy ?? null };
     }
     static toLink(x) {
         return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
@@ -199,6 +200,17 @@ export class PgStore {
     async setGrantScopes(id, scopes) {
         return ((await this.q("update bridge.grants set scopes = $2 where id = $1 and not revoked", [id, scopes])).rowCount ?? 0) === 1;
     }
+    async setGrantPolicy(id, policy) {
+        return ((await this.q("update bridge.grants set policy = $2 where id = $1 and not revoked", [id, policy === null ? null : JSON.stringify(policy)])).rowCount ?? 0) === 1;
+    }
+    async setAccountPolicy(id, policy) {
+        return ((await this.q("update bridge.accounts set policy = $2 where id = $1", [id, JSON.stringify(policy)])).rowCount ?? 0) === 1;
+    }
+    async recentCallsForGrants(grantIds, limit) {
+        if (grantIds.length === 0)
+            return [];
+        return (await this.q("select * from bridge.audit_events where kind = 'tool' and grant_id = any($1) order by id desc limit $2", [[...grantIds], limit])).rows.map(PgStore.toRow);
+    }
     async setAccountPrivacy(id, c) {
         const cl = await this.pool.connect();
         try {

package/dist/oauth/provider.js

@@ -8,6 +8,8 @@ import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-f
 import { Keyring, isValidCodeChallenge, randomToken, safeEqual, sha256Hex, verifyPkce } from "./crypto.js";
 import { approvePage, choosePage, consentPage, errorPage, instancePage, scopePage, secretPage, usernamePage, welcomePage } from "./pages.js";
 import { LoginError, PaperclipLogin } from "./paperclip-login.js";
+import { parseAccountPolicy, parseSessionPolicy, readAccountPolicy, readSessionPolicy, surfaceOfTool } from "../access/policy.js";
+import { tools as ALL_TOOLS } from "../tools.js";
 import { VERSION } from "../version.js";
 import { MemoryStore } from "./store.js";
 import { SCOPES, grantableScopes, isScope, maxRank, normalizeScope, normalizeScopes, scopeAllows, scopesUpTo } from "./scopes.js";
@@ -16,6 +18,8 @@ const PENDING_TTL_MS = 10 * 60_000;
 const CODE_TTL_MS = 60_000;
 const MAX_PENDING = 5000;
 const MAX_INSTANCE_ATTEMPTS = 5;
+/** Every tool name, for checking a session's tool list. */
+const KNOWN_TOOLS = new Set(ALL_TOOLS.map((t) => t.name));
 /** The plugin offered on the instance step: one fixed package, pinned to this bridge's own version (both are released together). */
 const PLUGIN_PACKAGE = "papercliped-paperclip-plugin";
 /** Its id inside Paperclip (the manifest id), used to see whether it is already installed. */
@@ -305,7 +309,52 @@ export class OAuthProvider {
     async manageConnections(accountId) {
         return (await this.store.listAccountGrants(accountId))
             .filter((g) => !g.revoked && g.clientId !== "paperclip-plugin")
-            .map((g) => ({ id: g.id, app: g.clientName, level: levelOf(g.scopes), createdAt: g.createdAt, lastUsedAt: g.lastUsedAt }));
+            .map((g) => {
+            const p = readSessionPolicy(g.policy, KNOWN_TOOLS);
+            return { id: g.id, app: g.clientName, label: p.label, level: levelOf(g.scopes), tools: p.tools, agents: p.agents, createdAt: g.createdAt, lastUsedAt: g.lastUsedAt };
+        });
+    }
+    /** What the policy engine checks on every call for this grant: the account's switch plus this session's limits. */
+    async policyFor(grant) {
+        const account = grant.accountId ? await this.store.getAccount(grant.accountId) : undefined;
+        return { account: readAccountPolicy(account?.policy), session: readSessionPolicy(grant.policy, KNOWN_TOOLS) };
+    }
+    async manageGetPolicy(a) {
+        return readAccountPolicy((await this.store.getAccount(a.id))?.policy);
+    }
+    /** Replace the access switch and per-agent overrides. Throws PolicyInputError on anything invalid. Takes effect on the next call. */
+    async manageSetPolicy(a, raw) {
+        const next = parseAccountPolicy(raw);
+        if (!(await this.store.setAccountPolicy(a.id, next)))
+            throw new Error("No such account");
+        await this.event("updated", { accountId: a.id, username: displayName(a) }, `mode_${next.mode}`);
+        return next;
+    }
+    /** Change one session: its name, tools, agents and (optionally) its access level. False if it isn't this account's live session. */
+    async manageSetSession(a, grantId, change) {
+        const g = await this.store.getGrant(grantId);
+        if (!g || g.revoked || g.accountId !== a.id || g.clientId === "paperclip-plugin")
+            return null;
+        const before = readSessionPolicy(g.policy, KNOWN_TOOLS);
+        const next = parseSessionPolicy({ label: change.label === undefined ? before.label : change.label, tools: change.tools === undefined ? before.tools : change.tools, agents: change.agents === undefined ? before.agents : change.agents }, KNOWN_TOOLS);
+        if (!(await this.store.setGrantPolicy(g.id, next)))
+            return null;
+        if (change.level)
+            await this.store.setGrantScopes(g.id, scopesUpTo(change.level));
+        await this.event("updated", { accountId: a.id, username: displayName(a) }, "session_limits");
+        return next;
+    }
+    /** The tools, as the control room lists them: what each does and which surface it is on. */
+    manageTools() {
+        return ALL_TOOLS.map((t) => ({ name: t.name, title: t.title, description: t.description.slice(0, 240), access: t.access, surface: surfaceOfTool(t) }));
+    }
+    /** The newest tool calls through this account's sessions (names and outcomes only; never arguments or results). */
+    async manageActivity(a, opts) {
+        const grants = (await this.store.listAccountGrants(a.id)).filter((g) => g.clientId !== "paperclip-plugin");
+        const ids = opts.session ? grants.filter((g) => g.id === opts.session).map((g) => g.id) : grants.map((g) => g.id);
+        const byId = new Map(grants.map((g) => [g.id, readSessionPolicy(g.policy, KNOWN_TOOLS).label ?? g.clientName]));
+        const rows = await this.store.recentCallsForGrants(ids, Math.min(Math.max(1, opts.limit), 200));
+        return rows.map((r) => ({ at: r.at, tool: r.name, ok: r.ok, blocked: r.errorClass === "policy_blocked", status: r.status, error: r.errorClass, ms: r.totalMs, session: r.grantId, app: (r.grantId && byId.get(r.grantId)) || r.client }));
     }
     /** Change what a connected app may do: Read only or Full control. */
     async manageSetLevel(a, grantId, level) {

package/dist/oauth/store.js

@@ -239,6 +239,26 @@ export class MemoryStore {
         this.save();
         return true;
     }
+    async setGrantPolicy(id, policy) {
+        const g = this.d.grants[id];
+        if (!g || g.revoked)
+            return false;
+        g.policy = policy ? { ...policy, tools: policy.tools && [...policy.tools], agents: policy.agents && [...policy.agents] } : null;
+        this.save();
+        return true;
+    }
+    async setAccountPolicy(id, policy) {
+        const a = this.accts[id];
+        if (!a)
+            return false;
+        a.policy = { mode: policy.mode, agents: { ...policy.agents } };
+        this.save();
+        return true;
+    }
+    async recentCallsForGrants(grantIds, limit) {
+        const ids = new Set(grantIds);
+        return this.audit.filter((r) => r.kind === "tool" && r.grantId !== null && ids.has(r.grantId)).slice(-limit).reverse();
+    }
     async setAccountPrivacy(id, c) {
         const a = this.accts[id];
         if (!a)

package/dist/public-api/types.js

@@ -11,4 +11,4 @@ export const PUBLIC_WINDOWS = ["1h", "24h", "7d"];
 /** Why a sign-in or connect flow failed. Anything the bridge records outside this list is counted as `other`. */
 export const AUTH_FAILURE_REASONS = ["bad_credentials", "rate_limited", "denied", "expired", "unreachable", "invalid_instance", "too_many_attempts", "other"];
 /** Error classes of tool calls and protocol requests. Anything else is counted as `other`. */
-export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "internal", "other"];
+export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "policy_blocked", "internal", "other"];

package/dist/server.js

@@ -74,11 +74,11 @@ export function createHttpServer(config, http, opts = {}) {
         catch {
             return null; // unreadable credential, expired connection, or instance no longer allowed: an invalid token (the user reconnects)
         }
-        return { kind: "oauth", grantId: grant.id, client: grant.clientName, userId: grant.userId, username: grant.username ?? undefined, instance, scopes: grant.scopes, paperclip };
+        return { kind: "oauth", grantId: grant.id, client: grant.clientName, userId: grant.userId, username: grant.username ?? undefined, instance, scopes: grant.scopes, paperclip, policy: await oauth.policyFor(grant) };
     }
     const execFor = (p) => p.kind === "static"
         ? { client: baseClient, exec: { actor: { id: "static-token" }, audit } }
-        : { client: p.paperclip, exec: { scopes: p.scopes, actor: { id: p.grantId, client: p.client, userId: p.userId, instance: p.instance, username: p.username }, audit } };
+        : { client: p.paperclip, exec: { scopes: p.scopes, policy: p.policy, actor: { id: p.grantId, client: p.client, userId: p.userId, instance: p.instance, username: p.username }, audit } };
     const unauthorized = (res, invalid) => {
         const challenge = oauth ? oauth.challengeHeader(invalid ? "invalid_token" : undefined) : "Bearer";
         json(res, 401, { error: invalid ? "Invalid or expired token" : "Missing or invalid bearer token" }, { "WWW-Authenticate": challenge });

package/dist/site/site.js

@@ -20,6 +20,8 @@ const NAV = [
     { slug: "chatgpt", title: "ChatGPT setup" },
     { slug: "prompts", title: "Prompt gallery" },
     { slug: "permissions", title: "Permissions" },
+    { slug: "control-room", title: "The control room" },
+    { slug: "access-modes", title: "API only, Full or Agent only" },
     { slug: "manage", title: "Manage connections" },
     { slug: "paperclip-plugin", title: "Paperclip plugin" },
     { slug: "anonymous-mode", title: "Anonymous mode" },

package/docs/CONTROL-ROOM.md

@@ -0,0 +1,79 @@
+# The control room: audit, design and decisions
+
+How v2.4.0 turns the Papercliped plugin into a control room inside Paperclip. Written alongside the build. The user-facing guides are `site/docs/control-room.md` and `site/docs/access-modes.md`; this page is for people changing the code.
+
+Labels: **Observed** = read from Paperclip's installed source (2026.1001.0) or a live instance. **Decided** = a choice made for this release.
+
+## 1. What was asked
+- See every session (one connected AI app) and manage it from inside Paperclip: which tools it may use, and whether it applies to everyone or to selected agents.
+- Follow Paperclip's native design, as a control room.
+- Papercliped integrated into the app like agents: finely manageable access, **full control for every agent and the API by default**, and a main-page switch between **API only | Full | Agent only**.
+- Audit Paperclip to see what needs to be integrated with what, and document as we build.
+
+## 2. Audit of Paperclip (Observed)
+
+### What a plugin can be
+Paperclip 2026.1001.0 has a plugin system (alpha). The UI slot types are `page`, `detailTab`, `taskDetailView`, `dashboardWidget`, `sidebar`, `routeSidebar`, `sidebarPanel`, `projectSidebarItem`, `globalToolbarButton`, `appShellOverlay`, `toolbarButton`, `contextMenuItem`, `commentAnnotation`, `commentContextMenuItem`, `settingsPage`, `companySettingsPage`. Each needs a capability: `page` ← `ui.page.register`, `sidebar`/`routeSidebar` ← `ui.sidebar.register`, `detailTab` ← `ui.detailTab.register`, `dashboardWidget` ← `ui.dashboardWidget.register`.
+
+- `routeSidebar` replaces the company menu while a route is open. This is how Paperclip's own agent page gets its grouped left menu, so it is the native way to build a control room.
+- `detailTab` with `entityTypes: ["agent"]` adds a tab to every agent's page.
+- A plugin worker reads agents with `ctx.agents.list` (capability `agents.read`). The host supplies the verified company with every action call (`context.companyId`); the page's own parameters are never trusted for it.
+- A `routePath` is allowed only on `page`, `routeSidebar` and `companySettingsPage` slots. The 2.2.0 manifest put one on a `sidebar` slot, which is why Paperclip refused to install it (a bare `400`). The plugin's tests now run Paperclip's own `pluginManifestV1Schema`.
+- Paperclip refuses to **upgrade** a plugin whose new version asks for capabilities the old one didn't have (an admin must approve). Moving from 2.2.x to 2.4 therefore means remove and reinstall. Documented in `site/docs/paperclip-plugin.md`.
+- Install is `POST /api/plugins/install` (instance admin only), which runs `npm install <pkg>@<version> --ignore-scripts` into `~/.paperclip/plugins`, then validates the manifest (schema, API version, capabilities, route conflicts, minimum host version) and registers it.
+
+### What Paperclip already has that overlaps
+- **Tool access** (`/companies/:id/tools/*`, `/tool-connections`, `/tool-profiles`, grants and delegations) and a **tool gateway** (`/tool-gateway/*`, MCP gateways). These govern the tools *agents* use *outward* (GitHub, Google, remote MCP connectors). Papercliped is the opposite direction: AI apps controlling Paperclip *inward*. **Decided:** do not reuse or mirror them; they model a different thing, and a plugin can't extend them. The per-agent **Tools** tab in Paperclip's own UI (`AgentToolsTab`) is the closest native pattern, and is why Papercliped's per-agent control lives on the agent's own page too.
+- **Agent permissions** (`PATCH /agents/:id/permissions`), **authorization grants and policies** (capabilities `authorization.*`). These are Paperclip-side permissions for principals inside Paperclip. **Decided:** not used. Papercliped's limits are enforced by the bridge, which every AI call passes through, so they hold for Claude, ChatGPT and any MCP client regardless of Paperclip's version, and need no extra capability.
+- **Agent sessions** (`agent.sessions.*`, `task-sessions`, `runtime-state`). These are an agent's own runtime conversations. They are not Papercliped sessions. In the control room a **session** always means a connected AI app (an OAuth grant).
+
+### Native design (Observed from `ui/` and a live page)
+shadcn-style components on Tailwind with CSS variables (`--background`, `--card`, `--border`, `--primary`, `--sidebar-accent`, …), light and dark via a `.dark` class, Inter, Lucide icons at 16px. The plugin uses Paperclip's **own compiled classes** (every class used is checked against the live stylesheet, see `plugin/src/ui/look.ts`), the SDK's `StatusBadge`, `MetricCard`, `DataTable` and toast, and Lucide icons. On touch screens Paperclip forces buttons to at least 44px, so controls size themselves from their buttons instead of a fixed height.
+
+## 3. Design
+
+### Sessions
+A **session** is one OAuth grant (one connected AI app). `Grant.policy` (new, nullable JSON) holds `{ label, tools, agents }`; `null` for `tools` or `agents` means "all". The access **level** stays in `grant.scopes`.
+
+### The access switch
+`Account.policy` (new, nullable JSON) holds `{ mode: "api"|"full"|"agent", agents: { [agentId]: "api"|"full"|"agent"|"off" } }`. No row means Full for every agent, so nothing changes for anyone until they choose.
+
+### Tool surfaces (`src/access/policy.ts`)
+Every tool is exactly one of **read** (any read, and `GET` through the raw API tool), **agent** (create/update/comment on issues, wake agent: it hands work to agents), or **api** (every other change: pause, resume, clear error, budget, terminate, goals, approvals, non-`GET` raw API). A mode allows `read` plus: `api` → api, `agent` → agent, `full` → both. A test ties `site/docs/access-modes.md` and the generated tool reference to this classification.
+
+### Enforcement order (`evaluate`, called from `executeTool`)
+1. Session tool list. 2. For each agent the call is about (named, assigned or owner, or the assignee of the named issue): Off → refuse; the agent's (or default) mode must allow the surface; the session's agent list must include it. 3. With no agent named, the default mode must allow the surface. 4. A session limited to selected agents may only use tools that name an agent (plus companies, agents list and service status), because every other view looks across all agents. The access level (scopes) is checked before all of this, unchanged.
+
+Refusals are `403` with `{ message, policy: <code> }`, audited as `policy_blocked`, and never reach Paperclip. The message names the setting and where to change it.
+
+### Hiding agents (`src/access/guard.ts`)
+For agents set to **Off**, the Paperclip client handed to every tool is wrapped so each response has those agents' records removed (list items, rows keyed by agent id, anything referencing them), **before** the tool builds its answer. A report built from that client cannot name a hidden agent because it never received one. Server-side totals are left as the server computed them (documented). For a session limited to selected agents, `paperclip_list_agents` is narrowed to those agents.
+
+An issue's agent is not named in the call, so for sessions with limits or accounts with per-agent settings the bridge looks the issue up once (`GET /issues/:id`) before deciding; if that fails, a limited session is refused and anyone else lets the tool report the real error.
+
+### What the AI is shown
+`visibleTools(scopes, policy)` drops tools that can never run for the session (not in its tool list; no mode allows the surface; tools that look across all agents for a limited session). Tools that *might* run for some agent stay.
+
+### Management API (`src/manage/routes.ts`)
+`GET /sessions`, `POST|DELETE /sessions/:id`, `GET|POST|PUT /policy`, `GET /tools`, `GET /activity`. Input is parsed strictly (`parseAccountPolicy`, `parseSessionPolicy`): unknown tool names, empty lists, bad ids and over-long lists are refused; damaged stored JSON falls back to the safe default instead of failing a call. Activity is read from the audit table by grant id and never contains arguments or results.
+
+### Plugin (`plugin/`)
+New worker actions: `sessions`, `setSession`, `policy`, `setPolicy`, `tools`, `activity`, `agents`. Five slots: `sidebar` (entry), `page` (the control room), `routeSidebar` (its menu), `detailTab` on agents, `dashboardWidget`. Navigation is `/papercliped?s=<section>&id=<thing>` so links, back and reload work. The access switch is a three-position vertical switch with a sliding knob (arrow keys, announced as a radio group, reduced-motion respected); the same control is reused compactly for agents.
+
+### Database
+`007_control_room.sql`: `accounts.policy jsonb`, `grants.policy jsonb`. No backfill. The panel views expose neither column. The generated `docs/supabase-schema.sql` is regenerated and a test fails if it is stale.
+
+## 4. How it was verified
+- **Rule engine**: unit tests for every mode, per-agent override, Off, session tool and agent lists, issue assignee, redaction, validation and damaged-row fallback (`test/policy.test.ts`).
+- **End to end through the real server** with a fake Paperclip: switching modes changes the next call, nothing blocked reaches Paperclip, Off agents vanish from lists and reports, limited sessions, another account is never affected, activity includes blocked calls and no arguments (`test/control-room.test.ts`).
+- **Postgres**: the whole suite (memory, Postgres, and the least-privilege role) ran against a real PostgreSQL 16, including the new store methods.
+- **Plugin**: handlers against a fake bridge, the SDK test harness (capabilities are enforced there), and the UI (`plugin/test`).
+- **Paperclip's own validators**: the built manifest passes `pluginManifestV1Schema` and the host's capability validator, run on the live instance's installed code.
+- **Visual**: every page, the agent tab and the widget were rendered with Paperclip's real stylesheet in light, dark and phone width.
+
+## 5. Known limits and next steps
+- Limits apply to calls through Papercliped. The Paperclip key Papercliped holds still has the account's access (see `docs/SECURITY.md`); a bridge compromise bypasses them.
+- Server-summed totals include Off agents.
+- Activity is capped at 200 rows per request and, on the hosted service, kept 30 days (`BRIDGE_AUDIT_RETENTION_DAYS`).
+- The plugin could not be installed into a live Paperclip with these slots before release; the manifest was validated against the live host's code instead. First live install after release should be checked: left menu replaces the company menu on `/papercliped`, the agent tab appears, the widget can be added.
+- Paperclip's plugin API is alpha; `routeSidebar` and `detailTab` behaviour may change.

package/docs/SECURITY.md

@@ -3,7 +3,7 @@
 Read this before running the bridge for people other than yourself.
 
 ## What you are holding
-For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's two access levels (Read only and Full control) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
+For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's limits (the two access levels, the API only / Full / Agent only switch, per-agent settings and per-session tool and agent lists, see `docs/CONTROL-ROOM.md`) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
 
 > **Headline risk:** a full compromise of the running bridge (code execution on the Render service *and* access to its environment) exposes every connected user's Paperclip with full board access, until those keys are revoked. Everything below reduces the likelihood or blast radius; none of it removes that risk. Until Paperclip offers scoped/short-lived keys, tell users plainly, encourage a dedicated Paperclip user for the connection, and keep the user base small enough to be comfortable with that.
 

package/docs/SITEMAP.md

@@ -29,6 +29,8 @@ One service, routed by host (`PUBLIC_HOSTS`, `src/web/`): `papercliped.co` the w
 | `/docs/manage` | Manage connections |
 | `/docs/paperclip-plugin` | Paperclip plugin |
 | `/docs/permissions` | Permissions |
+| `/docs/control-room` | The control room |
+| `/docs/access-modes` | API only, Full or Agent only |
 | `/docs/anonymous-mode` | Anonymous mode |
 | `/docs/public-api` | Public API and status |
 | `/docs/security` | Security |
@@ -54,7 +56,7 @@ One service, routed by host (`PUBLIC_HOSTS`, `src/web/`): `papercliped.co` the w
 | Path | Purpose |
 | --- | --- |
 | `GET /manage` | Old address: redirects to `/docs/paperclip-plugin` |
-| `/api/manage/*` | JSON API used by the Paperclip plugin (bearer token only, no cookies): `plugin-link/sign-in`, `me`, `connections`, `connections/:id`, `privacy`, `plugin-links`, `plugin-links/:id`, `secret/rotate`, `paperclip/disconnect`, `account/delete` (the last three need the secret key again) |
+| `/api/manage/*` | JSON API used by the Paperclip plugin (bearer token only, no cookies): `plugin-link/sign-in`, `me`, `connections`, `connections/:id`, `sessions`, `sessions/:id`, `policy`, `tools`, `activity`, `privacy`, `plugin-links`, `plugin-links/:id`, `secret/rotate`, `paperclip/disconnect`, `account/delete` (the last three need the secret key again) |
 | Domain section in the plugin **(planned v3)** | Pro members: address, tunnel status, token, port, release |
 
 ## 4. AI client endpoints

package/docs/supabase-schema.sql

@@ -274,6 +274,17 @@ update bridge.grants
    set scopes = array(select distinct s from unnest(array_replace(scopes, 'paperclip:admin', 'paperclip:control')) as s order by s desc)
  where 'paperclip:admin' = any(scopes);
 
+-- ───── 007_control_room.sql ─────
+-- Control room: who may do what through Papercliped.
+--   accounts.policy  the access switch (api | full | agent) and per-agent overrides, as JSON. Null = Full for every agent.
+--   grants.policy    one session's limits (a name, which tools, which agents), as JSON. Null = no limits beyond its access level.
+-- The app validates both on the way in and falls back to the safe default on anything it can't read, so old rows need no backfill.
+alter table bridge.accounts add column if not exists policy jsonb;
+alter table bridge.grants   add column if not exists policy jsonb;
+
+-- Audit rows now also record calls the policy refused (error_class = policy_blocked).
+comment on column bridge.audit_events.error_class is 'invalid_input | insufficient_scope | read_only | policy_blocked | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal';
+
 -- ───── migration bookkeeping ─────
 create table if not exists bridge.schema_migrations (version text primary key, applied_at timestamptz not null default now());
 alter table bridge.schema_migrations enable row level security;
@@ -283,6 +294,6 @@ do $$ declare r text; begin
     if exists (select 1 from pg_roles where rolname = r) then execute format('revoke all on bridge.schema_migrations from %I', r); end if;
   end loop;
 end $$;
-insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql') on conflict (version) do nothing;
+insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql'), ('007_control_room.sql') on conflict (version) do nothing;
 
 commit;

package/migrations/007_control_room.sql

@@ -0,0 +1,9 @@
+-- Control room: who may do what through Papercliped.
+--   accounts.policy  the access switch (api | full | agent) and per-agent overrides, as JSON. Null = Full for every agent.
+--   grants.policy    one session's limits (a name, which tools, which agents), as JSON. Null = no limits beyond its access level.
+-- The app validates both on the way in and falls back to the safe default on anything it can't read, so old rows need no backfill.
+alter table bridge.accounts add column if not exists policy jsonb;
+alter table bridge.grants   add column if not exists policy jsonb;
+
+-- Audit rows now also record calls the policy refused (error_class = policy_blocked).
+comment on column bridge.audit_events.error_class is 'invalid_input | insufficient_scope | read_only | policy_blocked | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Papercliped — connect Claude, ChatGPT and any MCP app to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + public stats API.",
   "license": "MIT",
   "type": "module",

package/site/docs/access-modes.md

@@ -0,0 +1,72 @@
+# API only, Full or Agent only
+
+One switch decides how AI apps may work with your Paperclip: **API only**, **Full** or **Agent only**. **Full** is the default for every agent. You set it in the [control room](/docs/control-room), and you can set any single agent differently (or turn it **Off**).
+
+## What each position means
+| Mode | AI apps can | AI apps can't |
+| --- | --- | --- |
+| **API only** | Look at everything, and control Paperclip directly: pause and resume agents, set budgets, decide approvals, manage goals, send API requests | Hand work to agents |
+| **Full** (default) | Everything: look, control directly, and work through agents | Nothing is held back by the switch |
+| **Agent only** | Look at everything, and work through agents: create, assign and comment on issues, wake an agent | Control Paperclip directly |
+
+The AI app's access **level** (Read only or Full control) still applies on top. Read only can never change anything, whatever the switch says.
+
+## The three kinds of tool
+Every tool is exactly one of these:
+
+| Kind | Tools | Allowed in |
+| --- | --- | --- |
+| **Look** | Everything that only reads: lists, details, reports, sync, waiting for an agent, and raw `GET` requests | Every mode |
+| **Work through agents** | Create issue, Update issue, Comment on issue, Wake agent now | Full, Agent only |
+| **Direct control** | Pause agent, Resume agent, Clear agent error, Set agent budget, Terminate agent, Create goal, Update goal, Decide approval, and raw API requests that aren't `GET` | Full, API only |
+
+The full list, with what each tool does, is the [tool reference](/docs/tools).
+
+## One agent at a time
+Each agent can follow the default or be set apart:
+
+- **API only**, **Full** or **Agent only** for just that agent. For example, keep the default **Full** but set one agent to **Agent only**: AI apps can give it work but can't pause or terminate it.
+- **Off**: Papercliped can't see or touch that agent. It disappears from lists and reports, anything assigned to it is out of reach, and calls that name it are refused.
+
+A call is judged by the agent it is about: the agent it names, the agent it assigns work to, or the agent an issue is assigned to. A call that isn't about one agent (for example "list goals") follows the default.
+
+## One session at a time
+Each connected app (a **session**) can also be limited, whatever the switch says:
+
+- **Tools:** only the tools you tick.
+- **Agents:** only the agents you choose. The session then works with those agents only, and can't use views across every agent (reports, the org chart, goals, approvals).
+
+## How the layers combine
+Papercliped checks, in this order, and refuses at the first thing that doesn't allow the call:
+
+1. The session's **tool list** (if it has one).
+2. The agent's **setting**: Off refuses; otherwise its mode must allow this kind of tool.
+3. The session's **agent list** (if it has one).
+4. The access **level** (Read only, Full control).
+
+So a call goes through only if *every* layer allows it.
+
+## What the AI app sees
+- Tools that can **never** run for a session are left out of what it is shown, so it doesn't try them. A session limited to `List agents` and `Pause agent` sees exactly those two.
+- A refused call returns a message that says which setting stopped it and where to change it. In the API the response is `403` with `{ "error": { "message": "...", "policy": "<code>" } }`:
+
+| `policy` code | Meaning |
+| --- | --- |
+| `tool_not_allowed` | The session's tool list doesn't include this tool |
+| `mode_blocks` | The access switch (or that agent's setting) doesn't allow this kind of tool |
+| `agent_off` | The agent is turned off |
+| `agent_not_in_session` | The session applies to selected agents and this isn't one of them |
+| `needs_all_agents` | The session applies to selected agents, and this view looks across every agent (or the issue has no agent to check) |
+
+Blocked calls appear in [Activity](/docs/control-room) as **Blocked**, and count under `policy_blocked` in the aggregate error classes of the [public API](/docs/public-api).
+
+## Examples
+- *"I want Claude to run my agents but never change budgets or approvals."* Give that session **Tools: Work through agents + Look** (untick the Direct control tools), or set the switch to **Agent only**.
+- *"I want a reviewer app that only works on two agents."* Open its session, choose **selected agents**, tick the two. It can look at them, wake them and comment on their issues, and nothing else.
+- *"Keep my finance agent away from AI apps."* Agents → set it to **Off**.
+- *"Pause everything fast, but no new work."* Set the switch to **API only**.
+
+## Limits worth knowing
+- These settings apply to calls made **through Papercliped**. They don't change what your Paperclip account can do in Paperclip itself, and the Paperclip key Papercliped holds still has your account's access (see [Security](/docs/security)). They limit the AI app, not the key.
+- Totals the Paperclip server already summed (such as total spend) still include hidden agents. Lists, per-agent breakdowns and reports built from them don't.
+- Changing a setting takes effect on the next request. A call already running isn't interrupted.

package/site/docs/connect-your-paperclip.md

@@ -139,7 +139,7 @@ curl https://your-address/api/health
 ## 6. Connect Papercliped
 
 1. Add the connector in your AI app. In Claude: **Settings → Connectors → Add custom connector**, address `{{MCP}}/mcp`.
-2. Choose **Connect your Paperclip**, enter your public address (just the address, no path) and approve the request in your Paperclip.
+2. Choose **Connect your Paperclip**, enter your public address (just the address, no path) and approve the request in your Paperclip. The box **Also install the Papercliped plugin in my Paperclip** is ticked by default; it installs the [Paperclip plugin](/docs/paperclip-plugin) and its [control room](/docs/control-room) for you if you are your Paperclip's instance admin.
 3. Pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**. Every screen: [Create your account](/docs/signup).
 4. Send your first prompt: *"Catch me up on my Paperclip."* More in the [prompt gallery](/docs/prompts).
 

package/site/docs/control-room.md

@@ -0,0 +1,61 @@
+# The control room
+
+The control room is Papercliped inside Paperclip: one place to see every AI app connected to your Paperclip, what each is allowed to do, and what it has done. It opens from **Papercliped** in Paperclip's sidebar and uses Paperclip's own look, so it follows your theme.
+
+You need the [Paperclip plugin](/docs/paperclip-plugin) installed and your Papercliped account linked. Everything here takes effect on the app's **next request**: nothing needs reconnecting.
+
+## How it fits together
+Three things decide what an AI app can do. Papercliped checks all three on every call, and the strictest one wins.
+
+| Layer | Where you set it | Decides |
+| --- | --- | --- |
+| **Access switch** | Overview, Agents, dashboard widget, agent tab | Whether AI apps may control Paperclip directly, work through agents, or both ([API only, Full or Agent only](/docs/access-modes)), for every agent or one agent at a time |
+| **Session** | Sessions | Which tools one connected app may use, and which agents it applies to |
+| **Level** | Sessions | Read only or Full control, as chosen when the app connected ([Permissions](/docs/permissions)) |
+
+## The menu
+While the control room is open, Paperclip's left menu is replaced by Papercliped's, the same way it is on an agent's page. **Back to Paperclip** at the top returns you.
+
+### Overview
+The front page. The **access switch** is a three-position switch: **API only**, **Full** (the default) and **Agent only**. Click a position, or use the arrow keys when the switch has focus. It saves at once. Beside it: how many sessions you have, how many agents, the calls made today and how many were blocked, a short list of things that need a look (a session that never made a call, an agent turned off, blocked calls, a Paperclip key that is not connected), and the latest calls.
+
+### Sessions
+Every AI app connected through Papercliped is a **session**. Open one to change:
+
+- **Name.** Rename a session to tell two apps or two devices apart. Up to 60 characters.
+- **Level.** Read only or Full control.
+- **Tools.** *All tools* means every tool its level and the switch allow. Untick it to choose exactly which tools this session may use, grouped as **Look**, **Work through agents** and **Direct control**. When a session is Read only, tools that change things are greyed out with "Needs Full control".
+- **Agents.** *Everyone* (including agents you add later), or **selected agents**. A session limited to selected agents works only with those agents: it can look at them, pause them, wake them, give them work, and use issues assigned to them. It cannot use views across every agent, such as reports, the org chart, goals and approvals, because those would show agents it doesn't apply to. The page says so when you choose it.
+- **Recent calls** for just this session, and **Disconnect**.
+
+Save with **Save changes** (it stays disabled until something changed and says what's wrong if a list is empty). **Discard** puts everything back.
+
+### Agents
+Papercliped follows the access switch for every agent. Here you can set any agent apart: **Default**, **API only**, **Full**, **Agent only** or **Off**.
+
+**Off** hides the agent completely. AI apps can't see it, can't touch it, and don't see anything assigned to it or its spending in lists and reports. Use it for agents you never want an AI app near.
+
+The default for every agent can also be changed from this page. Settings for agents that no longer exist (or are in another company) are listed so you can remove them.
+
+### Tools
+All tools an AI app can use, grouped by what they do, with what the switch allows right now and how many of your sessions can use each. Use it to answer "can my laptop session pause an agent?" without opening each session.
+
+### Activity
+The newest calls through your sessions: when, which session, which tool, and the result: **OK**, **Blocked** (by your settings) or **Failed** (with the reason, such as "Paperclip unreachable"). Filter by session, or to blocked and failed only. It refreshes every 20 seconds.
+
+Activity shows *what was used and what happened*. It never records what was sent to a tool or what came back. On the hosted service it is kept for 30 days.
+
+### Settings
+Privacy (appear anonymously in the service's logs), the Paperclips linked to your account, and the account itself (a new secret key, disconnect your Paperclip, delete the account). These ask for your secret key again. See [Anonymous mode](/docs/anonymous-mode).
+
+## In the rest of Paperclip
+- **An "Papercliped" tab on every agent's page.** Set what AI apps may do with *this* agent, and see which sessions reach it.
+- **A dashboard widget.** The access switch in small, with the number of sessions and blocked calls.
+- **A sidebar entry**, with the paperclip icon, under your other sections.
+
+## Good to know
+- These settings limit what AI apps can do **through Papercliped**. They don't change what your own Paperclip account can do in Paperclip itself.
+- A blocked call returns a plain message to the AI app saying which setting stopped it and where to change it, so it doesn't keep retrying. See [Limits and errors](/docs/limits-and-errors).
+- Tools that can never run for a session (switched off by the access switch or left out of its tool list) are not shown to the AI app at all.
+- Totals the Paperclip server already added up (for example total spend) still include hidden agents. Lists, reports by agent and anything built from them don't.
+- New permissions need approval in Paperclip. If you installed an earlier version of the plugin, remove it and install it again from **Settings → Plugins** to get the control room (see [Paperclip plugin](/docs/paperclip-plugin)).

package/site/docs/faq.md

@@ -27,6 +27,12 @@ Yes: run it locally with `npx papercliped@latest`. The hosted bridge needs a pub
 ## Why does pausing an agent fail with 403?
 Pause, resume, wake and approve need a Paperclip **board** token, and a connection at **Full control**. Check your level in the [Paperclip plugin](/docs/paperclip-plugin).
 
+## Why was a call blocked, or a tool missing?
+Your own settings. Open **Papercliped** in Paperclip: the switch (API only, Full, Agent only), an agent's setting, or the session's tool and agent lists decide what an AI app may do, and **Activity** shows each blocked call and the reason. See [API only, Full or Agent only](/docs/access-modes).
+
+## Can I keep an agent away from AI apps?
+Yes. In the [control room](/docs/control-room), open **Agents** and set it to **Off**: AI apps can't see it, touch it, or see what's assigned to it.
+
 ## How do I stop it?
 Disconnect the app on the manage page, revoke the key in your Paperclip, or delete your account. It stops at once.
 

package/site/docs/getting-started.md

@@ -30,7 +30,7 @@ This starts a local server for one Paperclip, using `PAPERCLIP_API_URL` and `PAP
 Any app that supports MCP can use Papercliped. See [Any AI app (MCP)](/docs/other-ai-apps).
 
 ## Inside your Paperclip
-The Papercliped plugin for Paperclip is where you manage everything: connected apps, levels, privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
+The Papercliped plugin for Paperclip is where you manage everything: the [control room](/docs/control-room) for connected apps, what each may do and which agents it applies to, plus privacy and your account. See [Paperclip plugin](/docs/paperclip-plugin).
 
 ## ChatGPT
 Papercliped publishes an OpenAPI description at `{{MCP}}/openapi.json` for GPT Actions. See [ChatGPT setup](/docs/chatgpt).

package/site/docs/limits-and-errors.md

@@ -21,6 +21,7 @@ Tool errors come back to your AI app with a message it can read. Over HTTP (Chat
 | --- | --- | --- | --- |
 | `400` | `invalid_input` | The request didn't match the tool's inputs | Usually the AI retries with fixed input |
 | `403` | `insufficient_scope` | The connection's level is too low for this tool | Switch the app to Full control in the [Paperclip plugin](/docs/paperclip-plugin) |
+| `403` | `policy_blocked` | Your settings don't allow this call: the access switch, an agent's setting, or the session's tool or agent list. The error carries a `policy` code (see [API only, Full or Agent only](/docs/access-modes)) | Change the setting in the [control room](/docs/control-room) if you want it allowed |
 | `403` | `read_only` | The bridge runs with `PAPERCLIP_READ_ONLY` | Ask the operator |
 | `401`, `403`, `404`, `409`… | `upstream_4xx` | Paperclip refused (e.g. your Paperclip key was revoked: reconnect) | Check the message |
 | `5xx` | `upstream_5xx` | Paperclip had an error | Try again later |

package/site/docs/manage-api.md

@@ -14,7 +14,14 @@ The token has no scopes: it can't call MCP, Actions or any Paperclip tool. It la
 | --- | --- |
 | `POST /plugin-link/sign-in` | Link: username + secret key → plugin token |
 | `GET /me` | Name, anonymity, connected Paperclip |
-| `GET /connections` | Connected apps with level and last use |
+| `GET /connections` | Connected apps with level and last use (also `GET /sessions`, which is the same list under the name the control room uses) |
+| `GET /sessions` | Sessions: each with `label`, `level`, `tools` (or `null` for all) and `agents` (or `null` for everyone) |
+| `POST /sessions/:id` `{ "label", "tools", "agents", "level" }` | Change one session. Leave a field out to keep it; `null` clears a limit. Takes effect on the next request |
+| `DELETE /sessions/:id` | Disconnect a session |
+| `GET /policy` | The access switch and per-agent settings: `{ "mode": "api" \| "full" \| "agent", "agents": { "<agent id>": "api" \| "full" \| "agent" \| "off" } }` |
+| `POST /policy` (or `PUT`) | Replace them with the same shape |
+| `GET /tools` | Every tool with its `access` and its `surface` (`read`, `agent` or `api`) |
+| `GET /activity?session=:id&limit=:n` | The newest tool calls (names and outcomes only), up to 200 |
 | `POST /connections/:id` `{ "level": "read" \| "control" }` | Change an app's level |
 | `DELETE /connections/:id` | Disconnect an app |
 | `POST /privacy` `{ "anonymous": true }` | Turn anonymity on or off |
@@ -26,6 +33,10 @@ The token has no scopes: it can't call MCP, Actions or any Paperclip tool. It la
 
 The last three need your secret key in the request.
 
+A session's `tools` must be known tool names and `agents` agent ids; an empty list is refused (use `null` for "all"). Per-agent settings equal to the default are dropped. See [API only, Full or Agent only](/docs/access-modes).
+
+The activity list holds, for each call: `at`, `tool`, `ok`, `blocked`, `status`, `error` (a coarse class such as `policy_blocked`), `ms`, `session` and `app`. It never holds what was sent to a tool or what came back.
+
 ## Errors
 `400` bad input, `401` wrong username or key when linking, or the token is unknown, expired or revoked, `403` wrong secret key for a sensitive action, `404` no such connection or link (also for other people's), `429` too many requests.
 

package/site/docs/paperclip-plugin.md

@@ -1,15 +1,17 @@
 # Paperclip plugin
 
-The Papercliped plugin is where you manage Papercliped, right inside Paperclip: a **Papercliped** entry in the sidebar and a page where you see every connected AI app, switch each between **Read only** and **Full control**, disconnect apps, turn anonymity on or off, and look after your account.
+The Papercliped plugin puts Papercliped inside Paperclip. It adds the [control room](/docs/control-room): a **Papercliped** entry in the sidebar that opens a page where you see every connected AI app, choose what each may do and which agents it applies to, set [API only, Full or Agent only](/docs/access-modes) for every agent or one at a time, read what was used and what was blocked, and look after your account. It also adds a **Papercliped** tab on every agent's page and a widget for the dashboard.
 
-It manages your Papercliped account only. It never reads or controls your Paperclip itself, and AI apps still connect through Papercliped as before.
+The plugin manages your Papercliped account and the limits on AI apps. It reads your agents' names, roles and status to list them, and never changes anything in Paperclip. AI apps still connect through Papercliped as before.
 
 ## Install (Paperclip admin)
 **Automatic (recommended).** When you connect your Paperclip from an AI app, the address step has a box, ticked by default: **Also install the Papercliped plugin in my Paperclip**. After you approve the sign-in, Papercliped asks your Paperclip to install it using Paperclip's own installer and your own approved key. It installs one fixed package, `papercliped-paperclip-plugin`, at the exact version that matches the service, and only when you are the Paperclip's instance admin. If you are not an admin, if it is already installed, or if your Paperclip can't install plugins, nothing happens and your connection works as usual. Untick the box to skip it.
 
 **By hand.** Install the npm package `papercliped-paperclip-plugin` from **Settings → Plugins** in Paperclip (instance admin only). You can remove it there at any time, whichever way it was installed.
 
-The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), and add a sidebar entry and a page.
+The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), read agents (to list them), and add a sidebar entry, a page with its own menu, an agent tab and a dashboard widget.
+
+**Updating from an earlier version.** Paperclip won't update a plugin to a version that asks for new permissions without an admin's approval, so go to **Settings → Plugins**, remove Papercliped, and install it again (or connect your Paperclip again with the install box ticked). You may need to link your account again; your Papercliped account, sessions and settings are kept at Papercliped and are not affected.
 
 The bridge address defaults to `https://papercliped.co`. If you host your own bridge, change **Papercliped bridge URL** in the plugin's settings. It must be `https`.
 
@@ -22,13 +24,22 @@ Papercliped checks the key once and hands the plugin a link token. The key itsel
 Lost your secret key? Connect from your AI app again and choose **Connect your Paperclip**: you keep your account and get a new key.
 
 ## What you can do
-- **Connected apps:** see each app's level and when it was last used, switch it between Read only and Full control (it applies on the app's next request), or disconnect it.
-- **Privacy:** appear anonymously in the service's logs, or switch back.
-- **Linked Paperclips:** see every Paperclip linked to your account, unlink this one, or remove an old one.
-- **Account** (asks for your secret key again):
-  - **Make a new secret key.** Shown once. The old key stops working and other linked Paperclips have to link again; this one stays linked.
-  - **Disconnect my Paperclip.** Papercliped forgets your Paperclip key and asks your Paperclip to revoke it. Every app stops working and the plugin unlinks. Your account stays.
-  - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
+The [control room](/docs/control-room) has six sections:
+
+- **Overview:** the access switch (API only, Full, Agent only), your numbers, and what needs a look.
+- **Sessions:** every connected app. Name it, set its level, choose its tools and which agents it applies to, see its recent calls, or disconnect it. It applies on the app's next request.
+- **Agents:** what Papercliped may do with each agent, including turning one off.
+- **Tools:** every tool, by what it does and what your settings allow.
+- **Activity:** recent calls, including the ones that were blocked.
+- **Settings:**
+  - **Privacy:** appear anonymously in the service's logs, or switch back.
+  - **Linked Paperclips:** see every Paperclip linked to your account, unlink this one, or remove an old one.
+  - **Account** (asks for your secret key again):
+    - **Make a new secret key.** Shown once. The old key stops working and other linked Paperclips have to link again; this one stays linked.
+    - **Disconnect my Paperclip.** Papercliped forgets your Paperclip key and asks your Paperclip to revoke it. Every app stops working and the plugin unlinks. Your account stays.
+    - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
+
+Outside the control room: the **Papercliped tab** on an agent's page sets what AI apps may do with that one agent, and the **dashboard widget** shows the access switch in small.
 
 ## Good to know
 - The plugin runs as trusted code inside Paperclip, so install it only from the official package. The automatic install is limited to that one package and to the version that matches the service, and it is always your choice on the connect screen.

package/site/docs/permissions.md

@@ -7,6 +7,14 @@ You decide how much the AI may do each time you connect. There are two levels.
 | **Read only** (default) | View agents, tasks, goals, costs and reports. Cannot change anything. |
 | **Full control** | Every tool: everything above, plus pause, resume, wake or terminate agents, create and update issues and goals, comment, decide approvals, change budgets and send any API request. Run your Paperclip from anywhere, without opening the dashboard. |
 
+## Beyond the two levels
+The level is chosen when an app connects. After that, the [control room](/docs/control-room) gives you finer control, without reconnecting anything:
+
+- **An access switch** for every agent: [API only, Full or Agent only](/docs/access-modes), and any agent can be set differently or turned off.
+- **Per-session limits:** name a session, choose exactly which tools it may use, and choose whether it applies to everyone or only selected agents.
+
+These only ever narrow what a level allows; they never grant more than the level.
+
 ## Good to know
 - Papercliped enforces these levels itself on every call, and refuses anything outside the level you chose.
 - Your Paperclip key has the access your Paperclip account has. The levels limit what the **AI app** can do through Papercliped; they do not shrink the key itself. That is why the key is stored encrypted and why you can revoke it at any time.

package/site/docs/public-api.md

@@ -47,7 +47,7 @@ curl "{{URL}}/api/public/v1/stats?window=24h"
 
 **Sign-in failure reasons** (a fixed list): `bad_credentials`, `rate_limited`, `denied`, `expired`, `unreachable`, `invalid_instance`, `too_many_attempts`, `other`.
 
-**Error classes** (a fixed list): `invalid_input`, `insufficient_scope`, `read_only`, `upstream_4xx`, `upstream_5xx`, `upstream_unreachable`, `rate_limited`, `unauthorized`, `internal`, `other`. Anything the service records outside these lists is counted as `other`, never shown as text.
+**Error classes** (a fixed list): `invalid_input`, `insufficient_scope`, `read_only`, `policy_blocked`, `upstream_4xx`, `upstream_5xx`, `upstream_unreachable`, `rate_limited`, `unauthorized`, `internal`, `other`. Anything the service records outside these lists is counted as `other`, never shown as text.
 
 ## Series
 Each bucket has `t` (start time), `requests`, `errors`, `faults`, `p95Ms`, `authCompleted`, `authFailed` and `newUsers`. Every bucket in the window is present, with zeros when nothing happened.

package/site/docs/tools.md

@@ -6,42 +6,42 @@ Raw API calls (`paperclip_api_request`) need Read only for GET and Full control
 
 ## Read only (17)
 
-| Tool | What it does | Changes anything? |
-| --- | --- | --- |
-| **List companies** `paperclip_list_companies` | List the companies the credential can access. Use this first to find a companyId. | No |
-| **Org chart** `paperclip_org_chart` | Return the company's full agent org tree (who reports to whom). | No |
-| **List agents** `paperclip_list_agents` | List all agents in a company with status, role and budget/spend. | No |
-| **Get agent** `paperclip_get_agent` | Get one agent including its chain of command and current status. | No |
-| **List goals** `paperclip_list_goals` | List the goal hierarchy for a company. | No |
-| **List projects** `paperclip_list_projects` | List projects in a company. | No |
-| **List issues** `paperclip_list_issues` | List issues/tasks. status may be comma-separated, e.g. 'todo,in_progress'. | No |
-| **Get issue** `paperclip_get_issue` | Get an issue with project, goal, ancestors and plan document. | No |
-| **List approvals** `paperclip_list_approvals` | List approval requests (hires, plans, budget overrides). Filter client-side by status if needed. | No |
-| **Sync snapshot** `paperclip_sync_snapshot` | One-call picture of the company right now: dashboard counters, every agent's status, and live runs. Call at the start of a session to sync with the agents. | No |
-| **Changes since cursor** `paperclip_sync_changes` | Poll for what changed. Pass the `cursor` returned by the previous call (omit the first time to get recent history). Returns new activity entries and the next cursor. | No |
-| **Wait for agent** `paperclip_wait_for_agent` | Block (polling) until an agent reaches one of the target statuses (default: idle or error) or the timeout passes. Use after waking an agent to follow it to completion. | No |
-| **Status report** `paperclip_report_status` | Executive status report: agents, tasks, spend, pending approvals, agents needing attention. | No |
-| **Cost report** `paperclip_report_costs` | Spend vs budget with per-agent and per-project breakdown. Defaults to the current month. | No |
-| **Agent performance report** `paperclip_report_agent_performance` | Per-agent throughput (done / in progress / blocked), spend and cost per completed task. | No |
-| **Activity digest** `paperclip_report_activity` | Digest of audit-log activity, optionally since an ISO timestamp (e.g. start of day). | No |
-| **Papercliped service status** `papercliped_service_status` | Is the hosted Papercliped service working? Returns its status (ok, degraded, down), version and aggregate 24-hour numbers (requests, success rate, latency, sign-ins). Public data only; does not touch Paperclip. | No |
+| Tool | What it does | Changes anything? | Works in |
+| --- | --- | --- | --- |
+| **List companies** `paperclip_list_companies` | List the companies the credential can access. Use this first to find a companyId. | No | Every mode |
+| **Org chart** `paperclip_org_chart` | Return the company's full agent org tree (who reports to whom). | No | Every mode |
+| **List agents** `paperclip_list_agents` | List all agents in a company with status, role and budget/spend. | No | Every mode |
+| **Get agent** `paperclip_get_agent` | Get one agent including its chain of command and current status. | No | Every mode |
+| **List goals** `paperclip_list_goals` | List the goal hierarchy for a company. | No | Every mode |
+| **List projects** `paperclip_list_projects` | List projects in a company. | No | Every mode |
+| **List issues** `paperclip_list_issues` | List issues/tasks. status may be comma-separated, e.g. 'todo,in_progress'. | No | Every mode |
+| **Get issue** `paperclip_get_issue` | Get an issue with project, goal, ancestors and plan document. | No | Every mode |
+| **List approvals** `paperclip_list_approvals` | List approval requests (hires, plans, budget overrides). Filter client-side by status if needed. | No | Every mode |
+| **Sync snapshot** `paperclip_sync_snapshot` | One-call picture of the company right now: dashboard counters, every agent's status, and live runs. Call at the start of a session to sync with the agents. | No | Every mode |
+| **Changes since cursor** `paperclip_sync_changes` | Poll for what changed. Pass the `cursor` returned by the previous call (omit the first time to get recent history). Returns new activity entries and the next cursor. | No | Every mode |
+| **Wait for agent** `paperclip_wait_for_agent` | Block (polling) until an agent reaches one of the target statuses (default: idle or error) or the timeout passes. Use after waking an agent to follow it to completion. | No | Every mode |
+| **Status report** `paperclip_report_status` | Executive status report: agents, tasks, spend, pending approvals, agents needing attention. | No | Every mode |
+| **Cost report** `paperclip_report_costs` | Spend vs budget with per-agent and per-project breakdown. Defaults to the current month. | No | Every mode |
+| **Agent performance report** `paperclip_report_agent_performance` | Per-agent throughput (done / in progress / blocked), spend and cost per completed task. | No | Every mode |
+| **Activity digest** `paperclip_report_activity` | Digest of audit-log activity, optionally since an ISO timestamp (e.g. start of day). | No | Every mode |
+| **Papercliped service status** `papercliped_service_status` | Is the hosted Papercliped service working? Returns its status (ok, degraded, down), version and aggregate 24-hour numbers (requests, success rate, latency, sign-ins). Public data only; does not touch Paperclip. | No | Every mode |
 
 ## Full control (13)
 
-| Tool | What it does | Changes anything? |
-| --- | --- | --- |
-| **Pause agent** `paperclip_pause_agent` | Pause an agent: stops its heartbeats and cancels its active run. Reversible with resume. | Yes |
-| **Resume agent** `paperclip_resume_agent` | Resume a paused agent so heartbeats start again. | Yes |
-| **Clear agent error** `paperclip_clear_agent_error` | Move an agent from `error` back to `idle`. Keeps run history. Only valid for agents in error. | Yes |
-| **Wake agent now** `paperclip_wake_agent` | Manually trigger a heartbeat so the agent starts working immediately. | Yes |
-| **Set agent budget** `paperclip_set_agent_budget` | Set an agent's monthly budget in US cents (e.g. 5000 = $50). Agents auto-pause at 100%. | Yes |
-| **Terminate agent** `paperclip_terminate_agent` | PERMANENTLY deactivate an agent. Irreversible. Requires confirm=true; ask the human first and prefer pause. | Yes, can't be undone |
-| **Create goal** `paperclip_create_goal` | Create a goal. level is one of company/team/agent/task (default task). | Yes |
-| **Update goal** `paperclip_update_goal` | Update a goal's title, description or status (planned/active/achieved/cancelled). | Yes |
-| **Create issue** `paperclip_create_issue` | Create a task. Assigning it to an agent (assigneeAgentId) with status 'todo' is how you hand work to that agent. | Yes |
-| **Update issue** `paperclip_update_issue` | Change an issue's status, priority, assignee, title etc. Optional `comment` is added in the same call. | Yes |
-| **Comment on issue** `paperclip_comment_issue` | Add a markdown comment to an issue. Can wake the current assignee. | Yes |
-| **Decide approval** `paperclip_decide_approval` | Approve, reject, or request revision on an approval. Decisions bind agents, so confirm with the human. | Yes |
-| **Raw API request** `paperclip_api_request` | Call any Paperclip REST endpoint under /api (path like '/companies/{id}/routines'). For endpoints without a dedicated tool. DELETE and any non-GET require confirm=true. | Yes |
+| Tool | What it does | Changes anything? | Works in |
+| --- | --- | --- | --- |
+| **Pause agent** `paperclip_pause_agent` | Pause an agent: stops its heartbeats and cancels its active run. Reversible with resume. | Yes | Full, API only |
+| **Resume agent** `paperclip_resume_agent` | Resume a paused agent so heartbeats start again. | Yes | Full, API only |
+| **Clear agent error** `paperclip_clear_agent_error` | Move an agent from `error` back to `idle`. Keeps run history. Only valid for agents in error. | Yes | Full, API only |
+| **Wake agent now** `paperclip_wake_agent` | Manually trigger a heartbeat so the agent starts working immediately. | Yes | Full, Agent only |
+| **Set agent budget** `paperclip_set_agent_budget` | Set an agent's monthly budget in US cents (e.g. 5000 = $50). Agents auto-pause at 100%. | Yes | Full, API only |
+| **Terminate agent** `paperclip_terminate_agent` | PERMANENTLY deactivate an agent. Irreversible. Requires confirm=true; ask the human first and prefer pause. | Yes, can't be undone | Full, API only |
+| **Create goal** `paperclip_create_goal` | Create a goal. level is one of company/team/agent/task (default task). | Yes | Full, API only |
+| **Update goal** `paperclip_update_goal` | Update a goal's title, description or status (planned/active/achieved/cancelled). | Yes | Full, API only |
+| **Create issue** `paperclip_create_issue` | Create a task. Assigning it to an agent (assigneeAgentId) with status 'todo' is how you hand work to that agent. | Yes | Full, Agent only |
+| **Update issue** `paperclip_update_issue` | Change an issue's status, priority, assignee, title etc. Optional `comment` is added in the same call. | Yes | Full, Agent only |
+| **Comment on issue** `paperclip_comment_issue` | Add a markdown comment to an issue. Can wake the current assignee. | Yes | Full, Agent only |
+| **Decide approval** `paperclip_decide_approval` | Approve, reject, or request revision on an approval. Decisions bind agents, so confirm with the human. | Yes | Full, API only |
+| **Raw API request** `paperclip_api_request` | Call any Paperclip REST endpoint under /api (path like '/companies/{id}/routines'). For endpoints without a dedicated tool. DELETE and any non-GET require confirm=true. | Yes | GET: every mode; other methods: Full, API only |
 
-See [Permissions](/docs/permissions) for how levels work and how to change them.
+**Works in** is the [access switch](/docs/access-modes): *every mode* tools only look; *Full, Agent only* tools hand work to agents; *Full, API only* tools control Paperclip directly. See [Permissions](/docs/permissions) for how levels work and how to change them.

package/site/docs/troubleshooting.md

@@ -16,6 +16,10 @@
 
 **The AI says it can't change anything.** You connected with **Read only**. Disconnect and connect again, choosing **Full control**.
 
+**The AI says a tool isn't available, or a call was blocked.** Check the access switch, the agent's setting and the session's limits in the [control room](/docs/control-room). The message the AI gets says which one. **Activity** lists blocked calls with the reason.
+
+**The control room shows no agents.** Open a company first: agents are listed for the company you're in. If you installed an older version of the plugin, remove it in **Settings → Plugins** and install it again so it can read agents.
+
 **My username is rejected.** It needs 6 to 32 characters including at least one number or one of `.` `#` `_`, and only letters, numbers and those symbols. It may also be taken.
 
 **Still stuck?** Open an issue at https://github.com/OpenSourcx/papercliped/issues. Never include your secret key or Paperclip keys.