@idea-base/mcp-server 2.0.0 → 2.2.0

package/README.md

@@ -85,8 +85,24 @@ Ask Claude to manage your projects:
 | Tool | Description |
 |------|-------------|
 | `log_time` | Log time against a task with notes |
-| `start_working` | Mark yourself as actively working on a task (surfaces the saved resume context + recent work notes so a cold session re-orients) |
-| `stop_working` | Stop active work on a task (optionally capture a `note` and/or `resume_context` on the way out) |
+| `start_working` | Open a timed work session on a task, and mark yourself actively working (surfaces the saved resume context + recent work notes so a cold session re-orients). Calling it twice never opens a second session — it resumes or reports the one you have |
+| `pause_working` | Pause the open session without ending it, with a required `reason` |
+| `resume_working` | Close the pause and carry on in the same session |
+| `stop_working` | Close the session with a UTC end instant and drop the active flag (optionally capture a `note` and/or `resume_context` on the way out). Fails if you have no open session |
+
+**Sessions are measured, and the pause reason decides the number.** `start_working`
+records a UTC start instant, `stop_working` a UTC end instant, and each pause in
+between records both its boundaries plus why work stopped:
+
+| `reason` | Effect on worked time |
+|---|---|
+| `waiting_on_human` | **Excluded.** A person has to act before you can continue |
+| `waiting_on_agent` | **Counted.** A sub-agent blocked on another *active* sub-agent is still working |
+| `other` | Counted |
+
+Only waiting on the human is not working. Use `pause_working` rather than
+`stop_working` whenever you intend to carry on — `stop_working` ends the session
+and the reason is lost.
 
 ### Activity & Audit Trail
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idea-base/mcp-server",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "MCP Server for IDEA Base - AI-powered project management. Integrates with Claude Code, Cursor, and Windsurf.",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -226,6 +226,7 @@ async function apiRequest(endpoint, options = {}) {
 
   if (!response.ok) {
     let message = `API error: ${response.status}`;
+    let code = null;
     const contentType = (response.headers.get('content-type') || '');
     if (contentType.includes('json')) {
       try {
@@ -233,11 +234,20 @@ async function apiRequest(endpoint, options = {}) {
         if (typeof body?.error === 'string' && body.error) {
           message = body.error.slice(0, MAX_ERROR_CHARS);
         }
+        // Machine-readable discriminator, when the endpoint supplies one. A
+        // handler needs to tell "you have no open session" (a real answer the
+        // caller must see) apart from "that endpoint is not deployed yet"
+        // (an infrastructure fact it should degrade around), and string-matching
+        // a prose error message to decide that is how quiet bugs get written.
+        if (typeof body?.code === 'string' && body.code) code = body.code;
       } catch {
         // fall through to the generic status message
       }
     }
-    throw new Error(redact(message));
+    const error = new Error(redact(message));
+    error.status = response.status;
+    if (code) error.code = code;
+    throw error;
   }
 
   return parseJsonBody(text, response);
@@ -433,12 +443,34 @@ const tools = [
         },
         assignee_user_id: {
           type: 'string',
-          description: 'User ID to assign the task to. Must be a member of the same account. Omit to leave the task unassigned.',
+          description: 'User ID to assign the task to. Must be a member of the same account. Omit to leave the task unassigned. For a SECOND (or third, ...) assignee, do not call this again — use add_assignee after creation, since this field only ever sets a single owner at create time.',
         },
         parent_task_id: {
           type: 'number',
           description: 'Make this a SUBTASK of the given task. The parent must be in the same project, and a subtask cannot itself have subtasks (one level only). A parent with subtasks takes its status from them: any subtask in progress makes the parent in progress, and all subtasks done makes it ready to complete.',
         },
+        verification_mode: {
+          type: 'string',
+          enum: ['manual', 'ai_review', 'ci_required', 'all'],
+          description: 'Gate this task\'s own completion. "manual" (default) allows a plain status change to done. "ai_review" or "all" BLOCK marking the task done (403 VERIFICATION_REQUIRED) until ai_completion_score reaches 0.8 — run "Verify with AI" first. "ci_required" or "all" BLOCK it until a PR is linked (github_pr_url) with passing CI. Setting this arms a real check against your own future attempt to close the task.',
+        },
+        github_pr_url: {
+          type: 'string',
+          description: 'URL of the GitHub Pull Request implementing this task. Used to fetch the PR diff for AI verification and to match incoming CI status (check_run/check_suite/workflow_run webhooks) back to this task.',
+        },
+        sort_order: {
+          type: 'number',
+          description: 'Position among the project\'s tasks (lower sorts first). NOT wired on the REST create path — POST /api/projects/:id/tasks always assigns MAX(sort_order)+1 and ignores this field on create. Set it after creation with update_task instead.',
+        },
+        is_milestone: {
+          type: 'boolean',
+          description: 'Mark this task as a milestone, drawn differently on the Gantt view. NOT wired on the REST create path — POST /api/projects/:id/tasks does not accept this field; the column is left at its default (0). Set it after creation with update_task instead.',
+        },
+        required_ci_checks: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Which named CI checks (matched case-insensitively as a substring of the check name) must pass for "ci_required"/"all" verification_mode to consider CI satisfied — e.g. ["build","test"]. Read by GET /api/tasks/:id/ci-status\'s resolveRequiredChecks (app/functions/api/tasks/[id]/ci-status.js:13-32), NOT by the GitHub webhook handler, which sets ci_status unconditionally from whichever single check/workflow event just arrived. Omit to leave unset (falls back to the project\'s own required_ci_checks, then to requiring every check). NOT wired on the REST create path — POST /api/projects/:id/tasks does not accept this field. Set it after creation with update_task instead.',
+        },
       },
       required: ['project_id', 'title'],
     },
@@ -483,7 +515,29 @@ const tools = [
         },
         assignee_user_id: {
           type: 'string',
-          description: 'User ID to assign the task to, replacing any existing assignee. Must be a member of the same account. Pass an empty string to unassign.',
+          description: 'User ID to assign the task to, REPLACING THE WHOLE assignee set (every non-active assignment row is deleted, active workers spared) — use this only when you want exactly one owner. Must be a member of the same account. Pass an empty string to unassign everyone (active workers still spared). To ADD a second assignee without touching the first, use add_assignee instead; to remove just one, use remove_assignee.',
+        },
+        verification_mode: {
+          type: 'string',
+          enum: ['manual', 'ai_review', 'ci_required', 'all'],
+          description: 'Gate this task\'s own completion. "manual" (default) allows a plain status change to done. "ai_review" or "all" BLOCK marking the task done (403 VERIFICATION_REQUIRED) until ai_completion_score reaches 0.8 — run "Verify with AI" first. "ci_required" or "all" BLOCK it until a PR is linked (github_pr_url) with passing CI. Setting this arms a real check against your own future attempt to close the task.',
+        },
+        github_pr_url: {
+          type: 'string',
+          description: 'URL of the GitHub Pull Request implementing this task. Used to fetch the PR diff for AI verification and to match incoming CI status back to this task. Pass an empty string to clear it.',
+        },
+        sort_order: {
+          type: 'number',
+          description: 'Position among the project\'s tasks (lower sorts first). Drives the order returned by list_tasks and the board/list views.',
+        },
+        is_milestone: {
+          type: 'boolean',
+          description: 'Mark this task as a milestone, drawn differently on the Gantt view. Pass false to unmark it.',
+        },
+        required_ci_checks: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Which named CI checks (matched case-insensitively as a substring of the check name) must pass for "ci_required"/"all" verification_mode to consider CI satisfied — e.g. ["build","test"]. Read by GET /api/tasks/:id/ci-status\'s resolveRequiredChecks (app/functions/api/tasks/[id]/ci-status.js:13-32), NOT by the GitHub webhook handler, which sets ci_status unconditionally from whichever single check/workflow event just arrived regardless of this field. Stored as a JSON array. Pass an empty array to require every check; this tool has no way to clear the column back to "inherit from project" (the REST API reserves that for an empty string, which this array-typed field cannot send).',
         },
         blocked_by: {
           type: 'array',
@@ -521,6 +575,90 @@ const tools = [
       required: ['task_id', 'status'],
     },
   },
+  {
+    name: 'add_assignee',
+    description: 'Assign a user to a task WITHOUT disturbing anyone already assigned. task_assignments holds one row per (task_id, user_id) — POST /api/tasks/:id/assignments upserts exactly that one row and leaves every other assignee alone, unlike update_task\'s assignee_user_id (which REPLACES the whole set — use that only when you actually want a single owner). This is the fix for the defect where a second MCP assignment silently dropped the first.\n\nIdempotent and is_active-safe: this checks the task\'s current assignees first, and if the user already holds a row (assigned OR actively working) it does nothing and says so, rather than re-POSTing. That matters because the REST endpoint\'s upsert OVERWRITES is_active on conflict — a blind re-assign of someone with a running timer (is_active=1, set by start_working) would silently stop their clock. Skipping the no-op re-POST is what keeps assignment and active-work presence independent.\n\nRejects a user who is not a member of this account (404, surfaced as an error) rather than creating a dangling assignment.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to assign the user to.',
+        },
+        user_id: {
+          type: 'string',
+          description: 'User ID to add as an assignee. Must be a member of the same account.',
+        },
+      },
+      required: ['task_id', 'user_id'],
+    },
+  },
+  {
+    name: 'remove_assignee',
+    description: 'Remove exactly one user\'s assignment from a task, leaving every other assignee untouched. DELETE /api/tasks/:id/assignments?user_id=... removes that one task_assignments row outright (both the assignment and any is_active flag on it) — this is a full unassign, not stop_working\'s "still assigned, no longer active" (use stop_working to end a work session without unassigning).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to remove the assignment from.',
+        },
+        user_id: {
+          type: 'string',
+          description: 'User ID to remove from the task\'s assignees.',
+        },
+      },
+      required: ['task_id', 'user_id'],
+    },
+  },
+  {
+    name: 'verify_task',
+    description: 'Run AI verification: grades this task\'s acceptance_criteria against the diff of its linked PR (a Haiku relevance pre-screen, then a Sonnet deep review) and PERSISTS the result to ai_completion_score / ai_completion_notes. This is exactly what update_task_status checks when the task\'s verification_mode is "ai_review" or "all" — call this to satisfy that gate yourself rather than repeatedly hitting 403 VERIFICATION_REQUIRED with no way through it.\n\nCOSTS MONEY — DO NOT LOOP THIS. Every call is metered via recordAIUsage and recorded to ai_generations (Sonnet, large PR-diff context) for audit. It runs FREE while your account is within its plan\'s included monthly verification cap; once over that cap each call is billed as AI credit overage — 2 credits per call on this account. Calling this repeatedly hoping for a higher score spends real credits for no guaranteed gain; if a genuine score lands below the 0.8 gate, that is a finding about the work, not a reason to retry.\n\nGRADES THE DIFF, NOT THE RUNNING SYSTEM. A high score means the PR\'s code changes look like they satisfy the criteria on paper — it is NOT proof the deployed/running behavior actually works. Never report this score as end-to-end verification; that is a human\'s job or an independent task-verify sub-agent\'s, not this tool\'s.\n\nRequires the task to already have non-empty acceptance_criteria (set via update_task) and a way to see the work: either the task\'s own github_pr_url (set via update_task) or a pr_url/work_description passed here. Fails with a clear message naming what is missing rather than grading an empty contract — refusal is free, no credits spent.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task to verify. Must already have non-empty acceptance_criteria.',
+        },
+        pr_url: {
+          type: 'string',
+          description: 'GitHub PR URL to grade against, for this call only — does not overwrite the task\'s stored github_pr_url. Omit to use the task\'s own linked PR.',
+        },
+        work_description: {
+          type: 'string',
+          description: 'Free-text description of the completed work to grade against. Used ONLY as a fallback when no PR diff is available (no pr_url given here and the task has no github_pr_url); ignored whenever a PR diff can be fetched.',
+        },
+      },
+      required: ['task_id'],
+    },
+  },
+  {
+    name: 'record_verification_feedback',
+    description: 'Record whether the most recent verify_task verdict on this task was accurate — calibration data, not a correction. Attaches to the latest ai_generations row of type completion_review for this task, so verify_task must have run at least once first. Does NOT change the stored ai_completion_score or re-run any model — it costs nothing (no Anthropic call, just an audit-log row) and is safe to call as often as useful.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task whose most recent verification you are giving feedback on.',
+        },
+        agreed: {
+          type: 'boolean',
+          description: 'Whether you agree the AI verdict (score + summary) was an accurate read of the work.',
+        },
+        actual_score: {
+          type: 'number',
+          description: 'Optional: the score (0.0-1.0) you believe was actually correct, if you disagree with the AI\'s score.',
+        },
+        notes: {
+          type: 'string',
+          description: 'Optional: why you agreed or disagreed.',
+        },
+      },
+      required: ['task_id', 'agreed'],
+    },
+  },
   {
     name: 'log_time',
     description: 'Log time spent on a task. This triggers a real-time notification showing time was logged.',
@@ -622,7 +760,7 @@ const tools = [
   },
   {
     name: 'start_working',
-    description: 'Mark that you are actively working on a task. This shows other team members that the task is being worked on and by whom.',
+    description: 'Start work on a task. Two things happen: you are shown to the team as actively working on it (and a todo task moves to in_progress), and a TIMED WORK SESSION is opened with a UTC start instant, so how long the task was actually worked becomes measurable instead of guessed.\n\nCalling it a second time on the same task NEVER opens a second session. If your session is paused it is resumed; if it is already running you are told so, with how long it has been going. The response always says which of the three happened.\n\nIt also orients a cold session: the response carries the task\'s resume context and its recent work notes, so read the whole thing before you start. Pair it with stop_working, and use pause_working when you have to wait on something.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -636,7 +774,7 @@ const tools = [
   },
   {
     name: 'stop_working',
-    description: 'Mark that you have stopped working on a task (break or switching tasks). Optionally capture your state on the way out: pass `note` to append a work note and/or `resume_context` to overwrite the resume block, so the next session can pick up where you left off.',
+    description: 'Stop working on a task: close your open work session with a UTC end instant, and drop the "actively working" flag (you stay assigned). The closed session is what makes the task\'s worked duration reportable.\n\nRequires an open session — if you have none this FAILS and writes nothing, rather than inventing a session with no start. Call start_working first.\n\nThis ENDS the session. If you are only waiting on something and intend to carry on afterwards, use pause_working instead: a pause keeps the session open and records why you stopped, which is what decides whether the interval counts as worked time.\n\nOptionally capture your state on the way out: pass `note` to append a work note and/or `resume_context` to overwrite the resume block, so the next session can pick up where you left off.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -656,6 +794,43 @@ const tools = [
       required: ['task_id'],
     },
   },
+  {
+    name: 'pause_working',
+    description: 'Pause your open work session without ending it, and record WHY. Use this whenever work stops but is not finished — you asked the human a question, you are waiting on another agent, you are blocked on a build.\n\nTHE REASON IS THE POINT, and it decides the number:\n  waiting_on_human — you are blocked on a person and CANNOT proceed. The paused interval is EXCLUDED from worked time.\n  waiting_on_agent — you are blocked on another agent or an automated run that is itself active. The interval IS COUNTED as worked time: a sub-agent blocked on another active sub-agent is still working.\n  other — anything else. Counted as worked.\n\nOnly waiting on the human is not working. Choose waiting_on_human ONLY when a person has to act before you can continue; if a machine or another agent is doing the work, it is waiting_on_agent.\n\nResume with resume_working. Do NOT use stop_working for a pause — that ends the session and the reason is lost.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task whose session to pause',
+        },
+        reason: {
+          type: 'string',
+          enum: ['waiting_on_human', 'waiting_on_agent', 'other'],
+          description: 'Why work stopped. waiting_on_human EXCLUDES this interval from worked time; waiting_on_agent and other INCLUDE it. Required — there is no default, because the whole worked-time figure turns on this value.',
+        },
+        detail: {
+          type: 'string',
+          description: 'Optional free text: what specifically you are waiting on (e.g. "asked whether to merge PR #280").',
+        },
+      },
+      required: ['task_id', 'reason'],
+    },
+  },
+  {
+    name: 'resume_working',
+    description: 'Resume your paused work session — closes the pause by recording the UTC instant you came back, so the paused interval has both boundaries and can be measured. The session itself was never closed and keeps its original start.\n\nFails if the session is not paused, rather than pretending to resume something. start_working also resumes a paused session, so use whichever reads better; this one does not re-fetch the orientation block.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        task_id: {
+          type: 'number',
+          description: 'The ID of the task whose session to resume',
+        },
+      },
+      required: ['task_id'],
+    },
+  },
   {
     name: 'add_work_note',
     description: 'Append a timestamped work note (status update) to a task\'s activity log. Use this to record progress so a future session can pick up where you left off (e.g. "finished auth handler, tests green, next: wire the callback"). Notes are append-only and never overwrite each other.',
@@ -897,7 +1072,12 @@ const toolHandlers = {
     };
   },
 
-  async create_task({ project_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, parent_task_id }) {
+  async create_task({ project_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, parent_task_id, verification_mode, github_pr_url, sort_order, is_milestone, required_ci_checks }) {
+    // sort_order, is_milestone and required_ci_checks are forwarded for parity
+    // with update_task, but POST /api/projects/:id/tasks does not destructure
+    // any of the three — it always assigns MAX(sort_order)+1 and leaves
+    // is_milestone/required_ci_checks at their column defaults. Sending them
+    // here is a silent no-op on create; use update_task right after to set them.
     const task = await apiRequest(`/projects/${project_id}/tasks`, {
       method: 'POST',
       body: JSON.stringify({
@@ -910,6 +1090,11 @@ const toolHandlers = {
         due_date,
         assignee_user_id,
         parent_task_id,
+        verification_mode,
+        github_pr_url,
+        sort_order,
+        is_milestone,
+        required_ci_checks,
       }),
     });
     return {
@@ -922,11 +1107,13 @@ const toolHandlers = {
     };
   },
 
-  async update_task({ task_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, blocked_by, blocked_reason }) {
+  async update_task({ task_id, title, description, acceptance_criteria, estimated_minutes, priority, start_date, due_date, assignee_user_id, blocked_by, blocked_reason, verification_mode, github_pr_url, sort_order, is_milestone, required_ci_checks }) {
     // Only forward what the caller actually named. An absent key leaves the
-    // field alone; an explicitly empty string is how a date or the assignee is
-    // cleared, and blocked_by is a REPLACE so an explicit [] must reach the
-    // API — which is why these are `!== undefined` rather than truthiness.
+    // field alone; an explicitly empty string is how a date, the assignee or
+    // the PR link is cleared, and blocked_by is a REPLACE so an explicit []
+    // must reach the API — which is why these are `!== undefined` rather than
+    // truthiness. is_milestone follows the same rule: `false` is a real value,
+    // not an absence, and must still reach the API.
     const updates = {};
     if (title !== undefined) updates.title = title;
     if (description !== undefined) updates.description = description;
@@ -938,6 +1125,11 @@ const toolHandlers = {
     if (assignee_user_id !== undefined) updates.assignee_user_id = assignee_user_id;
     if (blocked_by !== undefined) updates.blocked_by = blocked_by;
     if (blocked_reason !== undefined) updates.blocked_reason = blocked_reason;
+    if (verification_mode !== undefined) updates.verification_mode = verification_mode;
+    if (github_pr_url !== undefined) updates.github_pr_url = github_pr_url;
+    if (sort_order !== undefined) updates.sort_order = sort_order;
+    if (is_milestone !== undefined) updates.is_milestone = is_milestone;
+    if (required_ci_checks !== undefined) updates.required_ci_checks = required_ci_checks;
 
     const task = await apiRequest(`/tasks/${task_id}`, {
       method: 'PUT',
@@ -968,6 +1160,103 @@ const toolHandlers = {
     };
   },
 
+  async add_assignee({ task_id, user_id }) {
+    // Check first so an already-assigned (or already-active) user is never
+    // re-POSTed: the REST upsert overwrites is_active on conflict, and a
+    // blind re-assign would silently stop that person's running timer. See
+    // POST /api/tasks/:id/assignments' ON CONFLICT clause.
+    const current = await apiRequest(`/tasks/${task_id}/assignments`);
+    const assigned = current.assigned || [];
+    const active = current.active_workers || [];
+    const existing = [...assigned, ...active].find(a => a.user_id === user_id);
+
+    if (existing) {
+      const state = active.some(a => a.user_id === user_id) ? 'actively working' : 'assigned';
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `${user_id} is already ${state} on task ${task_id} — no change made. Other assignees are untouched.`,
+          },
+        ],
+      };
+    }
+
+    await apiRequest(`/tasks/${task_id}/assignments`, {
+      method: 'POST',
+      body: JSON.stringify({ user_id }),
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Assigned ${user_id} to task ${task_id}. Existing assignees, if any, were left in place.`,
+        },
+      ],
+    };
+  },
+
+  async remove_assignee({ task_id, user_id }) {
+    await apiRequest(`/tasks/${task_id}/assignments?user_id=${encodeURIComponent(user_id)}`, {
+      method: 'DELETE',
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Removed ${user_id} from task ${task_id}'s assignees. Other assignees are untouched.`,
+        },
+      ],
+    };
+  },
+
+  async verify_task({ task_id, pr_url, work_description }) {
+    const body = {};
+    if (pr_url !== undefined) body.pr_url = pr_url;
+    if (work_description !== undefined) body.work_description = work_description;
+
+    const result = await apiRequest(`/tasks/${task_id}/verify`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    const billingNote = result.billing?.type === 'ai_credit_overage'
+      ? `Billed ${result.billing.credits_charged} AI credit(s) as overage (over your plan's included verification cap).`
+      : 'Free platform feature — within your plan\'s included verification cap.';
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Verification score for task ${task_id}: ${result.score} (confidence: ${result.confidence}). ${billingNote} ` +
+                `This grades the PR diff against the acceptance criteria, not the running system.\n\n${JSON.stringify(result, null, 2)}`,
+        },
+      ],
+    };
+  },
+
+  async record_verification_feedback({ task_id, agreed, actual_score, notes }) {
+    const body = { agreed };
+    if (actual_score !== undefined) body.actual_score = actual_score;
+    if (notes !== undefined) body.notes = notes;
+
+    await apiRequest(`/tasks/${task_id}/verify-feedback`, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Feedback recorded for task ${task_id}'s most recent AI verification (agreed: ${agreed}).`,
+        },
+      ],
+    };
+  },
+
   async log_time({ task_id, minutes, notes, date }) {
     const entry = await apiRequest(`/tasks/${task_id}/time`, {
       method: 'POST',
@@ -1051,11 +1340,36 @@ const toolHandlers = {
   },
 
   async start_working({ task_id }) {
+    // Presence first, and unchanged: this is what writes the `started_working`
+    // task_events row and promotes a todo task to in_progress. The timed session
+    // below sits ALONGSIDE that audit trail, it does not replace it.
     await apiRequest(`/tasks/${task_id}/assignments`, {
       method: 'POST',
       body: JSON.stringify({ is_active: true }),
     });
 
+    // Open (or resume, or report) the work session. Non-fatal by design: the
+    // presence write already succeeded, and a session failure must not make
+    // start_working look like it did nothing.
+    let timing = '';
+    try {
+      const result = await apiRequest(`/tasks/${task_id}/work-session`, {
+        method: 'POST',
+        body: JSON.stringify({}),
+      });
+      const s = result.session || {};
+      if (result.action === 'resumed') {
+        const p = result.resumed_pause || {};
+        timing = `\n\nResumed work session #${s.id}, open since ${s.started_at} — the ${p.reason} pause that began at ${p.paused_at} is now closed. No second session was opened.`;
+      } else if (result.action === 'already_running') {
+        timing = `\n\nWork session #${s.id} was ALREADY running (started ${s.started_at}, ${s.worked_minutes} min worked so far). No second session was opened.`;
+      } else {
+        timing = `\n\nWork session #${s.id} opened at ${s.started_at} (UTC). Close it with stop_working; if you have to wait on something, use pause_working so the reason is recorded.`;
+      }
+    } catch (error) {
+      timing = `\n\n(Work session NOT recorded: ${error.message} — your presence flag is set, but no duration will be measured for this stretch.)`;
+    }
+
     // Orient a cold-starting session: surface the resume context + recent work notes.
     let orientation = '';
     try {
@@ -1088,7 +1402,7 @@ const toolHandlers = {
       content: [
         {
           type: 'text',
-          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.${orientation}`,
+          text: `Started working on task #${task_id}. Other team members can now see you are actively working on this task.${timing}${orientation}`,
         },
       ],
     };
@@ -1111,6 +1425,42 @@ const toolHandlers = {
       captured.push('resume context');
     }
 
+    // Close the session BEFORE dropping presence, so a task with no open
+    // session fails here and nothing at all is changed.
+    //
+    // A missing session is a real answer, not an infrastructure hiccup: it means
+    // the caller believes it was timing work that was never timed. Report it and
+    // stop, rather than writing a session row with no start or silently clearing
+    // the flag as if a duration had been recorded. Any OTHER session failure
+    // (the endpoint being unreachable, say) must not strand the presence flag,
+    // so that one is reported and the stop continues.
+    let timing = '';
+    let sessionError = null;
+    try {
+      const result = await apiRequest(`/tasks/${task_id}/work-session`, {
+        method: 'DELETE',
+        body: JSON.stringify({ state: 'completed' }),
+      });
+      const s = result.session || {};
+      const paused = Number(s.paused_minutes || 0);
+      const pausedText = paused > 0
+        ? ` (${s.elapsed_minutes} min elapsed, ${paused} min of that paused)`
+        : '';
+      timing = ` Work session #${s.id} closed at ${s.ended_at} — ${s.worked_minutes} minutes worked${pausedText}.`;
+    } catch (error) {
+      sessionError = error;
+    }
+
+    if (sessionError?.code === 'NO_OPEN_SESSION') {
+      throw new Error(
+        `${sessionError.message} Nothing was changed: no session row was written and ` +
+        'your active-work flag was left as it was.'
+      );
+    }
+    if (sessionError) {
+      timing = ` (Work session NOT closed: ${sessionError.message})`;
+    }
+
     await apiRequest(`/tasks/${task_id}/assignments?stop_only=true`, {
       method: 'DELETE',
     });
@@ -1120,7 +1470,51 @@ const toolHandlers = {
       content: [
         {
           type: 'text',
-          text: `Stopped working on task #${task_id}. You are still assigned to the task but no longer marked as actively working.${capturedText}`,
+          text: `Stopped working on task #${task_id}. You are still assigned to the task but no longer marked as actively working.${timing}${capturedText}`,
+        },
+      ],
+    };
+  },
+
+  async pause_working({ task_id, reason, detail }) {
+    const result = await apiRequest(`/tasks/${task_id}/work-session/pause`, {
+      method: 'POST',
+      body: JSON.stringify({ reason, note: detail }),
+    });
+    const p = result.pause || {};
+    const s = result.session || {};
+    const counted = result.counts_as_worked
+      ? 'This interval WILL count as worked time.'
+      : 'This interval will NOT count as worked time.';
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Paused work session #${s.id} on task #${task_id} at ${p.paused_at} (reason: ${reason}). ` +
+            `${counted} ${s.worked_minutes} minutes worked so far. ` +
+            'The session is still open — call resume_working when you are back.',
+        },
+      ],
+    };
+  },
+
+  async resume_working({ task_id }) {
+    const result = await apiRequest(`/tasks/${task_id}/work-session/resume`, {
+      method: 'POST',
+      body: JSON.stringify({}),
+    });
+    const p = result.resumed_pause || {};
+    const s = result.session || {};
+    return {
+      content: [
+        {
+          type: 'text',
+          text:
+            `Resumed work session #${s.id} on task #${task_id} at ${p.resumed_at}. ` +
+            `The ${p.reason} pause ran ${p.minutes} minutes and ` +
+            `${p.counts_as_worked ? 'COUNTS as worked time' : 'is EXCLUDED from worked time'}. ` +
+            `${s.worked_minutes} minutes worked on this session so far.`,
         },
       ],
     };