The best way to control Claude Code, Codex and more from any computer or phone
fix(server): agents see why a project update was refused instead of a generic failure (#30564)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
MarcoDotIO committed
Nov 5, 2026 at 23:33 UTC
7057a74d03d97bc2344f7eca0b417ba6a19b1ef4
5 files changed
+53
-12
apps/server/src/mcp/toolkits/project/handlers.test.ts
+28
@@ -664,3 +664,31 @@ it.effect("deleting a project through MCP also discards its clone record", () =>
664
expect(discarded).toEqual([harness.projectId]);
665
}),
666
);
667
+
668
+it.effect("an update the project refuses tells the agent why", () =>
669
+ Effect.gen(function* () {
670
+ const harness = clientLaunchHarness({ runtimeModeCeiling: "full-access", launched: [] });
671
+ const detail = "Project monograms must contain at most two characters.";
672
+ const dependencies = Layer.merge(
673
+ harness.dependencies,
674
+ Layer.mock(Project.ProjectService)({
675
+ update: (input) =>
676
+ Effect.fail(new Project.ProjectInvalidError({ projectId: input.projectId, detail })),
677
+ }),
678
+ );
679
+ const toolkit = yield* ProjectToolkit.pipe(
680
+ Effect.provide(
681
+ McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)),
682
+ ),
683
+ );
684
+
685
+ const refused = yield* toolkit
686
+ .handle("t3_project_update", {
687
+ projectId: harness.projectId,
688
+ projectIcon: { kind: "monogram", text: "ABC", color: "blue" },
689
+ })
690
+ .pipe(Stream.unwrap, Stream.runCollect, Effect.provide(dependencies));
691
+
692
+ expect(refused.at(-1)?.result).toMatchObject({ code: "invalid_request", message: detail });
693
+ }),
694
+);
apps/server/src/mcp/toolkits/project/handlers.ts
+7
-5
@@ -37,11 +37,13 @@ const isAboveCeilingError = Schema.is(OrchestratorRuntimeModeAboveCeilingError);
37
function projectFailure(error: Project.ProjectServiceError) {
38
if (error._tag === "ProjectOperationError") return unavailable();
39
const message =
40
- error._tag === "ProjectNotFoundError"
41
- ? "The project was not found."
42
- : error._tag === "ProjectConflictError"
43
- ? "The workspace is already registered to a project."
44
- : "The project is not empty; force=true is required to delete it.";
40
+ error._tag === "ProjectInvalidError"
41
+ ? error.detail
42
+ : error._tag === "ProjectNotFoundError"
43
+ ? "The project was not found."
44
+ : error._tag === "ProjectConflictError"
45
+ ? "The workspace is already registered to a project."
46
+ : "The project is not empty; force=true is required to delete it.";
47
return new OrchestratorMcpFailure({ code: "invalid_request", message });
48
}
49
apps/server/src/project/ProjectService.test.ts
+3
-6
@@ -452,15 +452,12 @@ it.layer(layerTest)("ProjectService", (it) => {
452
],
453
};
454
const first = yield* service.update(invalid).pipe(Effect.flip);
455
- assert.equal(first._tag, "ProjectOperationError");
455
+ assert.equal(first._tag, "ProjectInvalidError");
456
+ assert.include(first.message, "Script IDs must be 1-24 lowercase letters");
457
const replayed = yield* service
458
.update({ ...invalid, scripts: [{ ...invalid.scripts[0]!, id: "valid" }] })
459
.pipe(Effect.flip);
459
- assert.equal(replayed._tag, "ProjectOperationError");
460
- assert.include(
461
- String(replayed._tag === "ProjectOperationError" && replayed.cause),
462
- "Script ID",
463
- );
460
+ assert.deepEqual(replayed, first);
461
const receipts = yield* sql<{ readonly status: string; readonly aggregate_id: string }>`
462
SELECT status, aggregate_id FROM orchestration_command_receipts
463
WHERE command_id = ${invalid.commandId}
apps/server/src/project/ProjectService.ts
+13
@@ -84,6 +84,16 @@ export class ProjectNotEmptyError extends Schema.TaggedError<ProjectNotEmptyErro
84
}
85
}
86
87
+/** A change the project's rules refuse, such as an invalid script ID: the caller's input is wrong, nothing failed. */
88
+export class ProjectInvalidError extends Schema.TaggedError<ProjectInvalidError>()(
89
+ "ProjectInvalidError",
90
+ { projectId: ProjectId, detail: Schema.String },
91
+) {
92
+ override get message(): string {
93
+ return this.detail;
94
+ }
95
+}
96
+
97
export class ProjectOperationError extends Schema.TaggedError<ProjectOperationError>()(
98
"ProjectOperationError",
99
{
@@ -109,6 +119,7 @@ export type ProjectServiceError =
119
| ProjectNotFoundError
120
| ProjectConflictError
121
| ProjectNotEmptyError
122
+ | ProjectInvalidError
123
| ProjectOperationError;
124
125
export class ProjectService extends Context.Service<
@@ -292,6 +303,8 @@ export const make = Effect.gen(function* () {
303
});
304
case "ProjectCommandMissingProjectError":
305
return yield* new ProjectNotFoundError({ projectId });
306
+ case "ProjectCommandInvariantError":
307
+ return yield* new ProjectInvalidError({ projectId, detail: rejection.detail });
308
default:
309
return yield* dispatchError(
310
rejection ?? receipt.error ?? "The command was previously rejected.",
apps/server/src/project/http.ts
+2
-1
@@ -24,7 +24,8 @@ const failProjectMutation = Effect.fn("environment.projects.failMutation")(funct
24
if (
25
cause._tag === "ProjectNotFoundError" ||
26
cause._tag === "ProjectConflictError" ||
27
- cause._tag === "ProjectNotEmptyError"
27
+ cause._tag === "ProjectNotEmptyError" ||
28
+ cause._tag === "ProjectInvalidError"
29
) {
30
return yield* failEnvironmentInvalidRequest("invalid_command");
31
}