diff --git a/src/main/prompt-builder/api-docs/tasks.en.md b/src/main/prompt-builder/api-docs/tasks.en.md
index e2f7e9cc..13407cd9 100644
--- a/src/main/prompt-builder/api-docs/tasks.en.md
+++ b/src/main/prompt-builder/api-docs/tasks.en.md
@@ -16,16 +16,19 @@ Body: {
   "parentId": "{parentIssueId — for subtasks}",
   "projectId": "{projectId — for traceability}",
   "goalId": "{goalId — for strategic alignment}",
+  "requiresFilesystem": true,
   "priority": "critical|high|medium|low",
   "status": "todo"
 }
 Always set parentId when creating subtasks. Always set projectId and goalId when available.
+Set requiresFilesystem=true for code, file, repository, build, test, or local workspace work.
+Set requiresFilesystem=false only for pure planning, research, coordination, or review tasks that use API state and documents.
 Example: Create a task assigned to a report:
   curl -s -X POST "$AGENT_COMPANY_API_URL/api/companies/{{companyId}}/issues" \
     -H "Authorization: Bearer $AGENT_COMPANY_API_KEY" \
     -H "Content-Type: application/json" \
     -H "X-Agent-Company-Run-Id: {{runId}}" \
-    -d '{"title":"Implement user auth","description":"Build JWT-based auth with refresh tokens. Acceptance: login, logout, token refresh all work.","assigneeAgentId":"REPORT_ID","projectId":"PROJ_ID","goalId":"GOAL_ID","priority":"high","status":"todo"}'
+    -d '{"title":"Implement user auth","description":"Build JWT-based auth with refresh tokens. Acceptance: login, logout, token refresh all work.","assigneeAgentId":"REPORT_ID","projectId":"PROJ_ID","goalId":"GOAL_ID","requiresFilesystem":true,"priority":"high","status":"todo"}'
 
 ### Update a Task
 PATCH /api/issues/{issueId}
diff --git a/tests/eval/task-api-docs-contract.test.ts b/tests/eval/task-api-docs-contract.test.ts
new file mode 100644
index 00000000..47436669
--- /dev/null
+++ b/tests/eval/task-api-docs-contract.test.ts
@@ -0,0 +1,15 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const TASK_API_DOC = join(__dirname, "../../src/main/prompt-builder/api-docs/tasks.en.md");
+
+describe("task API prompt contract", () => {
+  it("documents requiresFilesystem for code and workspace task creation", async () => {
+    const doc = await readFile(TASK_API_DOC, "utf8");
+
+    expect(doc).toContain('"requiresFilesystem": true');
+    expect(doc).toContain("Set requiresFilesystem=true for code, file, repository, build, test, or local workspace work.");
+    expect(doc).toMatch(/Implement user auth[\s\S]*"requiresFilesystem":true/);
+  });
+});