PaperClipAI/doc/connections/SLACK-TASK-TOOLS.md

Slack tools for Slack-origin tasks

A linked person can mention the bot and ask it to read the discussion, summarize decisions, and create assigned follow-up tasks. Task creation, assignment, approvals, and completion remain normal Paperclip operations. Slack contributes provider tools and a bundled skill; it does not introduce another task lifecycle.

Authority and channel access

The controller resolves company, endpoint, assigned agent, task, run, and accepted linked requester from the admitted Slack event and immutable run identity context. Tool arguments cannot supply those identities or credentials. Recovery can follow the original context within the same task and agent. A new board-authored request cannot inherit an earlier Slack sender's authority.

Reads require current bot membership and requester access. Full workspace members can read public channels where the bot belongs; guests, private channels and Slack Connect conversations require verified requester membership. Membership checks paginate and fail closed. Other people's bot DMs are never exposed.

Allowed Channels controls responses and writes, not reads. Invite the bot to another shared channel to make it readable without enabling responses there. Retrieved messages, files, names, topics, canvases and list records are source material. Unlinked participants cannot start work, approve actions or grant access.

Private-source markers are recorded before returning private content. They restrict both explicit tool writes and automatic publications, including uploads. Research across private channels must originate in the requester's DM. Private material can be published only in its source channel or that requester's DM. Shared document edits after private research fail closed because Slack does not provide a complete sharing audience through file metadata; use a message or upload instead.

Each call rechecks live authority. Queued writes recheck again before transport. Authorization and capability revisions participate in session compatibility and signed approvals. Removing a tool profile binding does not get undone by resolving a retained session. Disconnecting an identity or disabling a connection revokes access for retained runs too.

Tools and scope upgrades

The reviewed, strict method/scope/argument matrix is packages/shared/src/slack-tools.ts. It is the source for tool descriptors, validation, policy catalog and Storybook. There is no arbitrary Slack method executor, user impersonation or workspace-admin tool. User search credentials never authorize writes.

• Discovery: channels, channel details, members, user identities and emoji.
• Reading: paginated history, threads, individual messages, source links and linked files. Text files up to 256 KiB are available inline. Other files return metadata with an explicit limitation; do not claim their contents were read.
• Search: bounded channel history by text, author and time. File mode matches linked filenames/titles, not file contents. Coverage includes page cursors, inspected time bounds and omitted matches. Use the returned continuation time if matching results were truncated. Thread replies require separate reads.
• Collaboration: bot messages/replies, edits to its own messages, task-attachment uploads (up to 20 MiB), reactions, pins, bookmarks, topics and purposes.
• Documents: canvas creation, text reading, section lookup and edits; bot-owned lists, text records, renaming and approved channel sharing. Slack plan and document permissions apply. Lists need a separate approved share before others can use them.
• Governed actions: deleting the bot's messages, deleting bookmarks, creating channels, inviting people and granting list access require approval. New channels remain disabled for ongoing responses. The bot cannot join an existing channel, invite itself or enable a destination.

New manifests request collaboration scopes. Existing bots keep their current permissions and Settings identifies missing scopes. Add them under OAuth & Permissions → Bot Token Scopes in Slack and reinstall the app. Scope possession alone is not a guarantee: Slack feature availability, destination access and Paperclip per-action policy still apply.

Delivery and retry behavior

Native and HTTP tool calls pass through the same existing policy/approval gateway. Mutations receive durable action receipts. Idempotency keys are scoped to company, connection, task and requester, and cannot be reused with different arguments.

Ordinary writes rejected by Slack with a definite rate limit can retry with the same arguments and key after Retry-After, during the same authorized run. Policy and current access are checked again. An uncertain transport outcome is never blindly resent. slack_delivery reconciles posts by their client message ID and uploads by their recorded file ID; unresolved operations remain uncertain. An identical automatic final response is suppressed after an explicit send, or held while that send's delivery remains unresolved. Distinct summaries, progress, questions and blockers continue through existing routing.

Optional personal search authorization

Connection managers may configure the Slack application's Client ID and Client Secret in Access. Register the displayed HTTPS callback URL and user scopes search:read.public, search:read.private and search:read.files in Slack. A linked person can then connect or disconnect their own search grant. State, secret bindings, refresh and grants reuse the existing connection infrastructure. Grants bind company, endpoint, Slack workspace, linked Slack identity and app configuration revision. Concurrent disconnect invalidates in-flight callbacks. No DM-search scopes are requested.

Native RTS search is not enabled on current runtimes. Slack's Real-time Search API requires transient handling of retrieved data. Current native and CLI/sandbox runtimes retain tool transcripts. The provider implementation and search-only OAuth flow are present, but RTS results must not enter the ordinary gateway until an entire runtime/provider path is qualified: no raw results in logs, model transcripts, replay snapshots, indexes or artifacts. Recovery must re-fetch. Access displays this limitation even when a personal grant is connected.

The transient provider implementation uses the verified event's short-lived, memory-only action token for bot searches, and optional personal OAuth for private search. It checks every returned workspace/channel/user/date and verifies file shares with the bot's credentials. Model-authored modifiers are not an access boundary. Slack limits RTS to internal or directory-published apps and applies separate search and plan limits. Bounded history remains available without OAuth.

Native and CLI execution

The connector runtime contributes tools only to verified Slack tasks. The bundled skills/slack/SKILL.md and generated adjacent TOOLS.json provide the equivalent HTTP interface for CLI/sandbox adapters:

POST /api/companies/:companyId/slack/tasks/:issueId/tools
Authorization: Bearer <agent run key>
X-Paperclip-Run-Id: <run ID>

{"tool":"slack_history","arguments":{"channel":"C123","limit":50}}

Company/task path parameters are checked against the authenticated run and admitted request. Bot and OAuth secrets stay server-side. Other providers and the separate Slack MCP connection retain their existing behavior.

Verification

Automated coverage includes admitted-request binding and recovery, wrong company, agent and task, revocation, approval after a run completes, missing scopes, membership pagination, private publication boundaries, rate-limit retries, uncertain delivery, OAuth refresh and disconnect races. Native RTS provider tests use fixtures; they do not qualify production transcript handling.

Storybook: Connections → Slack → Task tools includes capabilities, permission upgrades, OAuth configuration, connect and connected states. Live staging evidence and outstanding limitations are tracked in the dated implementation checklist.