Files
PaperClipAI/server/src/__tests__/agent-task-hierarchy-depth-routes.test.ts
T
DottaandClaude Opus 5.5 958f9aa9f3 feat(issues): limit agent-created task trees to parent and child (#19312)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Agents split work into tasks. A task can have a parent task.
> - Today agents can nest tasks to any depth: parent, child, grandchild,
and deeper.
> - Deep agent-made trees are hard to follow, and an agent that works on
a child task makes grandchildren by default.
> - This pull request limits agent-created trees to two levels: a
top-level task and its children.
> - A request for a grandchild does not fail. The server puts the new
task beside the requester and tells the agent.
> - Board users keep full control. They can still nest to any depth.
Existing deep trees stay valid.
> - The pull request also records which task created each new task, so
the audit trail stays complete when the parent changes.

## Linked Issues or Issue Description

No public issue exists. This is the feature description. Related: #16853
(budgets that include descendant work) also reasons about task trees;
this change does not alter its traversal.

**Subsystem affected**

Issues (tasks): create, child create and move in the issue service and
routes. Agent tools, chat suggestions and creation provenance use these
paths.

**Problem or motivation**

Agents create subtasks as deep as they want. An agent that runs on a
child task gets that child as the default parent, so its follow-ups
become grandchildren. The trees become deep and hard to read. The parent
link is also the only record of which task created a follow-up, so that
record is lost when the parent changes.

**Proposed solution**

Limit agent-created trees to a parent and its children. When an agent
asks for a grandchild, put the new task under the requester's parent and
return `parentAdjusted`. Do not reject the request. Keep board users
unrestricted. Record the originating task in a new server-set
`origin_issue_id` column. Keep `origin_run_id` as the originating run.

**Alternatives considered**

Reject grandchild requests with an error. We did not do this, because
agents then fail mid-task. Add a database constraint. We did not do
this, because existing deep trees must stay valid and nesting can return
later.

## What Changed

- Add `MAX_AGENT_TASK_HIERARCHY_DEPTH` (2) and the
`IssueParentAdjustment` type in `packages/shared`.
- Add `resolveNewTaskParent` and `planIssueParentChange` in
`server/src/services/issues.ts`. `create`, `createChild` and `update`
use the agent limit by default (`parentDepthPolicy: "flatten"`).
- The issue create, `/children` and PATCH routes pass `allow_nested` for
board users. For agents, the routes check authorization against the
parent that the server actually writes.
- The requester keeps its behavior when the server moves a task beside
it: `blockParentUntilDone` blocks the requester, and the new task
inherits the requester's workspace and privacy.
- The server never moves a task above a low-trust boundary root that
contains the requester.
- These subsystems keep any depth, because they find their work by
parent: watchdog reviews, monitor recovery, email-channel placement, and
routines that a person configured.
- An agent move of a task that has children skips only the parent change
and returns `reason: "has_children"`.
- Add `issues.origin_issue_id` (nullable, `on delete set null`, indexed)
in migration `0434`. Only the server sets it. The `createdFrom` detail
field, the `createdFromIssueId` filter and task-creation provenance read
it first.
- Chat prompts now let a chat agent create one task, a task with
children, or separate tasks. The conversation is never a parent.
- The runner `create_task` tool accepts an optional `parentTaskId`. A
chat agent can create a top-level task and then put subtasks under it.
The run must be able to read and change the parent. A conversation is
never a parent. The depth limit still applies. Project tools map the
field to `parentId` through the issue route. The protocol manifest,
semantic contracts and eval fixture are regenerated.
- Watchdog runs that have an active watchdog keep their requested parent
on all create paths, because their access is limited to the watched
subtree.
- Fix a bug that the test drive found: the chat (MCP) `create_task`
ignored the requested `status`, so a `backlog` task became `todo` and
started to run. It now uses the same rule as the native tool.
- Update `skills/paperclip`, `doc/SPEC-implementation.md`, and add the
plan `doc/plans/2026-11-05-two-level-task-hierarchy.md`.

## Verification

- `cd server && npx vitest run
src/__tests__/agent-task-hierarchy-depth.test.ts
src/__tests__/agent-task-hierarchy-depth-routes.test.ts`: 19 new tests
for service and route behavior, all pass.
- Related suites (64 files: issues service, thread interactions,
privacy, watchdogs, provenance, runner tool authority, decisions,
routines, project tools): 1208 tests pass. Two tests changed because of
the intended behavior and pass now. Two `email-channels.integration`
tests fail locally because the test cannot find a bundled skill file
from this worktree path. This change does not touch that code.
- `packages/db`: migration safety, snapshot drift and journal tests
pass.
- Typecheck passes for `server`, `packages/shared`, `packages/db`, `cli`
and `ui` (local `ui` errors come only from generated Storybook catalog
files that are absent).
- Local test drive on an isolated instance with real Claude agents: 29
of 29 use cases pass, including an agent on a child task (follow-ups
placed beside it, with the notice) and a chat that creates a top-level
task with three subtasks.
- I did not run the full `pnpm test:run` or `pnpm build` locally. CI
runs them.

## Risks

- Behavior change for agents: some follow-ups that were grandchildren
are now siblings. The parent of the requester is woken when all its
children finish, which now includes these tasks.
- The runner `create_task` input contract adds one optional field, so
the protocol manifest and the pack contract change. The tool output does
not change: it shows the actual `parentId`, and the activity log records
`parentAdjusted`.
- Migration `0434` adds a nullable column, a foreign key and an index.
It does not backfill rows.
- `IssueCreationSource.run` is now nullable.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use
(shell, file edits, local test runs).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 21:22:33 -06:00

193 lines
9.6 KiB
TypeScript

import { randomUUID } from "node:crypto";
import express from "express";
import request from "supertest";
import { and, eq } from "drizzle-orm";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { activityLog, agents, companies, createDb, heartbeatRuns, issues } from "@paperclipai/db";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
import { issueRoutes } from "../routes/issues.js";
import { errorHandler } from "../middleware/index.js";
const support = await getEmbeddedPostgresTestSupport();
const describePostgres = support.supported ? describe : describe.skip;
describePostgres("agent task hierarchy depth through the issue routes", () => {
let db: ReturnType<typeof createDb>;
let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
const companyId = randomUUID();
const agentId = randomUUID();
const rootId = randomUUID();
const childId = randomUUID();
const conversationId = randomUUID();
const runOnChild = randomUUID();
const runOnConversation = randomUUID();
const legacyConversationChildId = randomUUID();
beforeAll(async () => {
database = await startEmbeddedPostgresTestDatabase("paperclip-agent-task-depth-routes-");
db = createDb(database.connectionString);
await db.insert(companies).values({
id: companyId, name: "Paperclip", issuePrefix: "DEP", defaultResponsibleUserId: "board-user",
requireBoardApprovalForNewAgents: false,
});
await db.insert(agents).values({ id: agentId, companyId, name: "Coder", role: "engineer", adapterType: "codex_local", status: "active" });
await db.insert(issues).values([
{ id: rootId, companyId, title: "Ship the feature", identifier: "DEP-1", issueNumber: 1, status: "in_progress", assigneeAgentId: agentId },
{ id: childId, companyId, parentId: rootId, title: "Build the API", identifier: "DEP-2", issueNumber: 2, status: "in_progress", assigneeAgentId: agentId },
{ id: conversationId, companyId, title: "Chat", identifier: "DEP-3", issueNumber: 3, status: "in_review", assigneeAgentId: agentId,
conversationAgentId: agentId, conversationUserId: "board-user", conversationState: "waiting" },
]);
await db.insert(issues).values({
id: legacyConversationChildId, companyId, parentId: conversationId, title: "Legacy chat child",
identifier: "DEP-4", issueNumber: 4, status: "todo", assigneeAgentId: agentId,
});
await db.insert(heartbeatRuns).values([
{ id: runOnChild, companyId, agentId, scopeKind: "issue", issueId: childId, nativeIssueId: childId, status: "running", contextSnapshot: { issueId: childId } },
{ id: runOnConversation, companyId, agentId, scopeKind: "issue", issueId: conversationId, status: "running", contextSnapshot: { issueId: conversationId } },
]);
}, 30_000);
afterAll(async () => { await database?.cleanup(); });
const boardActor = { type: "board", userId: "board-user", source: "local_implicit", isInstanceAdmin: true } as Express.Request["actor"];
function agentActor(runId: string): Express.Request["actor"] {
return { type: "agent", companyId, agentId, runId, source: "agent_jwt", onBehalfOfUserId: null, onBehalfOfMemberships: [] } as Express.Request["actor"];
}
function app(actor: Express.Request["actor"]) {
const instance = express();
instance.use(express.json());
instance.use((req, _res, next) => { req.actor = actor; next(); });
instance.use("/api", issueRoutes(db, {} as never));
instance.use(errorHandler);
return instance;
}
async function activity(issueId: string, action: string) {
const [row] = await db.select().from(activityLog)
.where(and(eq(activityLog.entityId, issueId), eq(activityLog.action, action)));
return row ?? null;
}
const expectedAdjustment = {
reason: "max_agent_depth",
applied: true,
requestedParent: { id: childId, identifier: "DEP-2" },
effectiveParent: { id: rootId, identifier: "DEP-1" },
};
it("places a run's default follow-up beside the child task it is working on", async () => {
const created = await request(app(agentActor(runOnChild)))
.post(`/api/companies/${companyId}/issues`)
.send({ title: "Write the migration" });
expect(created.status, JSON.stringify(created.body)).toBe(201);
expect(created.body.parentId).toBe(rootId);
expect(created.body.originIssueId).toBe(childId);
expect(created.body.originRunId).toBe(runOnChild);
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
expect((await activity(created.body.id, "issue.created"))?.details).toMatchObject({
parentId: rootId,
parentAdjusted: expectedAdjustment,
parentDefaultedFromRunIssue: true,
});
const detail = await request(app(boardActor)).get(`/api/issues/${created.body.id}`);
expect(detail.body.createdFrom).toMatchObject({ issue: { id: childId, identifier: "DEP-2" } });
});
it("places an explicit agent grandchild beside the requester instead of failing", async () => {
const created = await request(app(agentActor(runOnChild)))
.post(`/api/companies/${companyId}/issues`)
.send({ title: "Add tests", parentId: childId });
expect(created.status, JSON.stringify(created.body)).toBe(201);
expect(created.body.parentId).toBe(rootId);
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
});
it("places an agent child created through the children route beside the requester", async () => {
const created = await request(app(agentActor(runOnChild)))
.post(`/api/issues/${childId}/children`)
.send({ title: "Update the docs" });
expect(created.status, JSON.stringify(created.body)).toBe(201);
expect(created.body.parentId).toBe(rootId);
expect(created.body.originIssueId).toBe(childId);
expect(created.body.parentAdjusted).toEqual(expectedAdjustment);
expect((await activity(created.body.id, "issue.child_created"))?.details).toMatchObject({
parentId: rootId,
requestedParentId: childId,
});
});
it("lets board users create grandchildren", async () => {
const created = await request(app(boardActor))
.post(`/api/companies/${companyId}/issues`)
.send({ title: "Board grandchild", parentId: childId });
expect(created.status, JSON.stringify(created.body)).toBe(201);
expect(created.body.parentId).toBe(childId);
expect(created.body).not.toHaveProperty("parentAdjusted");
const viaChildren = await request(app(boardActor))
.post(`/api/issues/${childId}/children`)
.send({ title: "Board grandchild via children route" });
expect(viaChildren.status, JSON.stringify(viaChildren.body)).toBe(201);
expect(viaChildren.body.parentId).toBe(childId);
});
it("flattens agent moves into a child and lets board users move freely", async () => {
const [agentMoved, boardMoved] = [randomUUID(), randomUUID()];
await db.insert(issues).values([
{ id: agentMoved, companyId, title: "Loose task", status: "todo", assigneeAgentId: agentId },
{ id: boardMoved, companyId, title: "Board loose task", status: "todo", assigneeAgentId: agentId },
]);
const byAgent = await request(app(agentActor(runOnChild)))
.patch(`/api/issues/${agentMoved}`)
.send({ parentId: childId });
expect(byAgent.status, JSON.stringify(byAgent.body)).toBe(200);
expect(byAgent.body.parentId).toBe(rootId);
expect(byAgent.body.parentAdjusted).toEqual(expectedAdjustment);
expect((await activity(agentMoved, "issue.updated"))?.details).toMatchObject({
parentId: rootId,
requestedParentId: childId,
parentAdjusted: expectedAdjustment,
});
const byBoard = await request(app(boardActor))
.patch(`/api/issues/${boardMoved}`)
.send({ parentId: childId });
expect(byBoard.status, JSON.stringify(byBoard.body)).toBe(200);
expect(byBoard.body.parentId).toBe(childId);
expect(byBoard.body).not.toHaveProperty("parentAdjusted");
});
it("records a top-level placement when an agent moves under a legacy conversation child", async () => {
const movingId = randomUUID();
await db.insert(issues).values({ id: movingId, companyId, parentId: rootId, title: "Move to top", status: "todo", assigneeAgentId: agentId });
const moved = await request(app(agentActor(runOnChild)))
.patch(`/api/issues/${movingId}`)
.send({ parentId: legacyConversationChildId });
expect(moved.status, JSON.stringify(moved.body)).toBe(200);
expect(moved.body.parentId).toBeNull();
expect(moved.body.parentAdjusted).toMatchObject({ reason: "max_agent_depth", effectiveParent: null });
expect((await activity(movingId, "issue.updated"))?.details).toMatchObject({
parentId: null,
requestedParentId: legacyConversationChildId,
});
});
it("lets a chat create a top-level task and a child under it", async () => {
const top = await request(app(agentActor(runOnConversation)))
.post(`/api/companies/${companyId}/issues`)
.send({ title: "Plan the launch", assigneeAgentId: agentId });
expect(top.status, JSON.stringify(top.body)).toBe(201);
expect(top.body.parentId).toBeNull();
expect(top.body.originIssueId).toBe(conversationId);
const child = await request(app(agentActor(runOnConversation)))
.post(`/api/companies/${companyId}/issues`)
.send({ title: "Draft the announcement", parentId: top.body.id, assigneeAgentId: agentId });
expect(child.status, JSON.stringify(child.body)).toBe(201);
expect(child.body.parentId).toBe(top.body.id);
// Both originate from the chat that created them.
expect(child.body.originIssueId).toBe(conversationId);
expect(child.body).not.toHaveProperty("parentAdjusted");
});
});