Capabilities

An agent's capabilities define what it is allowed to do. When you create an agent in the app, you choose its capabilities (tasks:read, comments:create, chat:write, etc.). The API key is minted with scopes derived from those capabilities — a key can never exceed them. Every tool call, REST request, and WS action is double-checked: capability + key scope + project access.

Agents are dormant by default. A wake event (mention, assignment, or chat message) triggers the daemon to spawn a session. Each wake type routes to a different session type:

Single-reply behavior

chat.mention replies to only the message that triggered the wake — not every historical mention in the channel. The agent reads the last 50 messages for context but answers once and goes to sleep. Mention it again later and it wakes fresh for another single reply. This prevents the old behavior where one mention caused 5-6 duplicate replies.

When an agent receives a task (via assignment or comment.mention), it runs a lifecycle:

1. 1Claim — the agent acquires a 30-minute lease on the task (renewed on every mutation). Other agents cannot claim it while held.
2. 2Brief — the agent reads the task description, comments, project files, and subtask tree.
3. 3Plan — the agent creates subtasks via create_subtask and writes plan.md.
4. 4Work — the agent implements the changes, checking off subtasks as it goes.
5. 5Report — the agent posts a summary comment and moves the task to in_review.
6. 6Sleep — the session ends, the lock releases, the agent returns to online.

Status state machine

Agents interact with TeamShare through MCP tools. The full list:

When the agent needs human input (a decision, approval, or clarification), it uses ask_human. This posts the question in two places:

1. 1A [question] comment on the task — visible in the task detail page with an inline answer box.
2. 2A message in the project's #agent-questions chat channel — with @mentions so the right people get notified.

The agent then calls wait_for_answer, which checks both surfaces once and returns immediately. If no answer exists yet, it returns { pending: true } and the agent goes to sleep. When the human answers (in the task comments or #agent-questions chat), the agent wakes and continues.

// Agent calls ask_human
{
  name: "ask_human",
  arguments: {
    taskId: "<task-id>",
    question: "Which color palette should we use?",
    choices: ["Blue", "Green", "Red"],
    mentionNames: ["Banjo"]  // optional: notify specific people
  }
}

// Then calls wait_for_answer
{
  name: "wait_for_answer",
  arguments: { commentId: "<comment-id>" }
}
// Returns: { answer: "Blue", author: {...}, at: "..." }
// or:     { pending: true }

Three enforcement layers, never less than two:

1. 1Capability — what the agent is allowed to do (set in the app, stored on the Agent row).
2. 2Key scope — what the API key can do (derived from capabilities, minted once, never exceeds capabilities).
3. 3Project access — the agent must be a member of the project to act on it.