fix: enforce task delegation policy

code-yeongyu · code-yeongyu · commit 9b81026c5e9d · 2026-05-16T16:42:30.000+09:00
Adds code-defined agent registration, nested task ancestry, default max-depth enforcement, allowedSubagents overrides, and frontmatter task permission checks before task runner startup.

QA: npm test; npm run check; npm run qa:import; npm run qa:process-kill; npm run qa:senpi-install; npm pack --dry-run
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1
+
+- Enforce nested task depth, allowed subagent overrides, and frontmatter task permissions.
+- Add code-defined agent registration helpers.
+
 ## 0.1.0
 
 - Initial task subagent extension package.
diff --git a/README.md b/README.md
@@ -12,6 +12,8 @@ Task subagent extension for the pi coding agent.
 - Session resume reconciliation through `~/.senpi/task/tasks/*.json`.
 - JSONL task logs under `~/.senpi/task/logs/*.jsonl` with secret-like fields redacted.
 - Agent frontmatter loading from `.pi`, `.senpi`, `~/.pi/agent`, `~/.senpi/agent`, and `~/.senpi/agents`.
+- Code-defined agents through `defineAgent()` and `registerAgent()`.
+- Nested task policy with default max depth `1`; `allowedSubagents` and task permissions can explicitly allow deeper calls.
 - Model fallback for `models: [provider/a, provider/b]`.
 - TUI footer/widget status plus `/tasks`, `/task-kill`, and a keyboard shortcut.
 
@@ -30,8 +32,11 @@ models:
 allowedSubagents:
   - github-librarian
   - web-librarian
+maxDepth: 1
 tools:
   read: allow
+  task:
+    "web-librarian": allow
   bash:
     "rg *": allow
 ---
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -9,7 +9,7 @@ Core rule: background task errors, abrupt process exits, resume state, and final
 ## Components
 
 - `agents`: markdown agent registry with pi/senpi-compatible search paths.
-- `permissions`: senpi-compatible last-match-wins rule evaluation.
+- `permissions`: senpi-compatible last-match-wins rule evaluation for task policy.
 - `runtime`: task state, result store, runners, resume reconciliation, and model fallback.
 - `tools`: `task`, `task_status`, `task_cancel`.
 - `ui`: compact status and widget rendering.
@@ -22,6 +22,18 @@ Process mode uses `ProcessTaskRunner` and `ProcessRunner`. It launches a separat
 
 `CompositeTaskRunner` routes by `task.executionMode`, so both modes share persistence, logging, cancellation, status UI, and fallback handling.
 
+## Agent Definition And Task Policy
+
+Markdown agents are loaded from project and user `.pi` / `.senpi` locations, including `~/.senpi/agents/agents`. Code can also define agents by importing `defineAgent()` or `registerAgent()` from `pi-task`.
+
+Nested tasks are enforced before a task record is created:
+
+- Top-level parent sessions may create depth-1 tasks.
+- Default `maxDepth` is `1`.
+- A parent agent's `allowedSubagents` permits the named target even beyond depth.
+- Frontmatter task permissions can allow or deny `task:<agent>` or `task` patterns.
+- Denied delegations return a `denied` status and do not start a runner.
+
 ## Persistence And Resume
 
 Task records are atomically written to `~/.senpi/task/tasks/<task-id>.json`. Final responses and errors remain available through `task_status` after the task finishes.
diff --git a/docs/planning-summary.md b/docs/planning-summary.md
@@ -22,6 +22,8 @@ Primary implementation choices:
 
 - In-process is the default runner.
 - Process mode is explicit through agent frontmatter or tool params.
+- Nested task depth is enforced before starting a task; `allowedSubagents` overrides the default max depth.
+- Agents can be markdown-loaded or code-registered.
 - Background state is first-class and retrievable by `task_status`.
 - Final responses and errors are persisted before the manager reports completion.
 - Abrupt process termination is represented as `killed`; unobservable resumed process tasks become `lost`.
diff --git a/docs/qa-results.md b/docs/qa-results.md
@@ -4,12 +4,12 @@ Status: PASSED
 
 Command-backed evidence from May 16, 2026:
 
-- `npm test`: passed, 17 files / 30 tests.
+- `npm test`: passed, 19 files / 37 tests.
 - `npm run check`: passed, `tsgo --noEmit` and `biome check .`.
 - `npm run qa:import`: passed, `import ok`.
 - `npm run qa:process-kill`: passed, child pid was reported and direct `SIGTERM` produced `killed`.
 - `npm run qa:senpi-install`: passed dry-run for `~/.senpi/agent/extensions/pi-task`.
-- `npm pack --dry-run`: passed, `pi-task-0.1.0.tgz`, 36 files.
+- `npm pack --dry-run`: passed, `pi-task-0.1.1.tgz`, 40 files.
 
 Manual QA scenario note:
 
diff --git a/docs/release.md b/docs/release.md
@@ -12,7 +12,7 @@ gh repo edit code-yeongyu/pi-task --description "Task subagent extension for pi"
 Release setup:
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
-gh release create v0.1.0 --generate-notes
+git tag v0.1.1
+git push origin v0.1.1
+gh release create v0.1.1 --generate-notes
 ```
diff --git a/docs/verifier.md b/docs/verifier.md
@@ -13,4 +13,4 @@ Approval requires:
 - Pi lifecycle/tool events are mapped in code and task logs redact sensitive fields.
 - Process mode records pid and external kill evidence.
 - In-process is the default.
-- Permissions, agent schema, and model fallback match `docs/spec.md`.
+- Permissions, default depth, allowed-subagent override, agent schema, code-defined agents, and model fallback match `docs/spec.md`.
diff --git a/evidence/manual-qa.md b/evidence/manual-qa.md
@@ -13,6 +13,7 @@ Verified manually:
 - `npm run qa:import` loads the extension default export.
 - `npm run qa:process-kill` records pid and reports `killed` after direct external `SIGTERM`.
 - `npm run qa:senpi-install` resolves the local install symlink target.
+- `npm test` now covers 19 files / 37 tests, including nested task policy and code-defined agents.
 - `senpi --help` confirms `senpi install <source>` and `--extension/-e` host support.
 - `command -v pi` returned no binary on this machine, so local host checks use `senpi`.
 
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "pi-task",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "Task subagent extension for the pi coding agent with background lifecycle visibility, resume, process supervision, and final-result retrieval.",
 	"type": "module",
 	"license": "MIT",
diff --git a/src/agents/code-agents.ts b/src/agents/code-agents.ts
@@ -0,0 +1,44 @@
+import type { AgentInfo } from "./schema.js";
+
+const registeredAgents = new Map<string, AgentInfo>();
+
+export type CodeAgentInput = Omit<Partial<AgentInfo>, "name" | "native" | "disable"> & {
+	name: string;
+	prompt: string;
+};
+
+export function defineAgent(input: CodeAgentInput): AgentInfo {
+	return {
+		name: input.name,
+		...(input.description !== undefined && { description: input.description }),
+		mode: input.mode ?? "all",
+		...(input.model !== undefined && { model: input.model }),
+		...(input.models !== undefined && { models: input.models }),
+		...(input.temperature !== undefined && { temperature: input.temperature }),
+		...(input.tools !== undefined && { tools: input.tools }),
+		permission: input.permission ?? [],
+		...(input.background !== undefined && { background: input.background }),
+		...(input.executionMode !== undefined && { executionMode: input.executionMode }),
+		...(input.maxTurns !== undefined && { maxTurns: input.maxTurns }),
+		...(input.maxDepth !== undefined && { maxDepth: input.maxDepth }),
+		allowedSubagents: input.allowedSubagents ?? [],
+		disallowedTools: input.disallowedTools ?? [],
+		disable: false,
+		prompt: input.prompt,
+		native: true,
+	};
+}
+
+export function registerAgent(input: CodeAgentInput | AgentInfo): AgentInfo {
+	const agent = "native" in input ? input : defineAgent(input);
+	registeredAgents.set(agent.name, agent);
+	return agent;
+}
+
+export function clearRegisteredAgents(): void {
+	registeredAgents.clear();
+}
+
+export function loadRegisteredAgents(): Record<string, AgentInfo> {
+	return Object.fromEntries(registeredAgents);
+}
diff --git a/src/agents/loader.ts b/src/agents/loader.ts
@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { loadRegisteredAgents } from "./code-agents.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { type AgentInfo, validateAgentConfig } from "./schema.js";
 
@@ -67,5 +68,6 @@ export async function loadAllAgents(cwd: string, homeDir: string = os.homedir())
 	for (const location of getConfigLocations(cwd, homeDir)) {
 		Object.assign(agents, await loadAgentsFromDirectory(location.dir));
 	}
+	Object.assign(agents, loadRegisteredAgents());
 	return agents;
 }
diff --git a/src/agents/schema.ts b/src/agents/schema.ts
@@ -13,6 +13,7 @@ export type AgentInfo = {
 	background?: boolean;
 	executionMode?: ExecutionMode;
 	maxTurns?: number;
+	maxDepth?: number;
 	allowedSubagents: string[];
 	disallowedTools: string[];
 	disable: boolean;
@@ -77,6 +78,7 @@ export function validateAgentConfig(name: string, frontmatter: unknown, body: st
 	const temperature = typeof source.temperature === "number" ? source.temperature : undefined;
 	const background = typeof source.background === "boolean" ? source.background : undefined;
 	const maxTurns = typeof source.maxTurns === "number" ? source.maxTurns : undefined;
+	const maxDepth = typeof source.maxDepth === "number" ? source.maxDepth : undefined;
 	const executionMode = readExecutionMode(source.executionMode);
 
 	return {
@@ -93,6 +95,7 @@ export function validateAgentConfig(name: string, frontmatter: unknown, body: st
 			...(background !== undefined && { background }),
 			...(executionMode !== undefined && { executionMode }),
 			...(maxTurns !== undefined && { maxTurns }),
+			...(maxDepth !== undefined && { maxDepth }),
 			allowedSubagents: allowedSubagents.value ?? [],
 			disallowedTools: disallowedTools.value ?? [],
 			disable: source.disable === true,
diff --git a/src/index.ts b/src/index.ts
@@ -13,6 +13,8 @@ import { createTaskCancelTool } from "./tools/task-cancel.js";
 import { createTaskStatusTool } from "./tools/task-status.js";
 import { formatTaskList, syncTaskStatusToUi } from "./ui/status.js";
 
+export { clearRegisteredAgents, defineAgent, registerAgent } from "./agents/code-agents.js";
+
 function isCancellableStatus(status: string): boolean {
 	return status === "queued" || status === "running" || status === "retrying";
 }
diff --git a/src/runtime/ancestry.ts b/src/runtime/ancestry.ts
@@ -0,0 +1,41 @@
+export type TaskAncestry = {
+	taskId: string;
+	agentType: string;
+	parentSessionId: string;
+	rootSessionId: string;
+	depth: number;
+};
+
+const inProcessAncestry = new Map<string, TaskAncestry>();
+
+export function registerInProcessAncestry(sessionId: string, ancestry: TaskAncestry): void {
+	inProcessAncestry.set(sessionId, ancestry);
+}
+
+export function clearInProcessAncestry(sessionId: string): void {
+	inProcessAncestry.delete(sessionId);
+}
+
+export function getInProcessAncestry(sessionId: string): TaskAncestry | undefined {
+	return inProcessAncestry.get(sessionId);
+}
+
+export function getEnvironmentAncestry(): TaskAncestry | undefined {
+	const taskId = process.env.PI_TASK_PARENT_TASK_ID;
+	const agentType = process.env.PI_TASK_AGENT_TYPE;
+	const parentSessionId = process.env.PI_TASK_PARENT_SESSION_ID;
+	const rootSessionId = process.env.PI_TASK_ROOT_SESSION_ID;
+	const depthRaw = process.env.PI_TASK_DEPTH;
+	if (
+		taskId === undefined ||
+		agentType === undefined ||
+		parentSessionId === undefined ||
+		rootSessionId === undefined ||
+		depthRaw === undefined
+	) {
+		return undefined;
+	}
+	const depth = Number.parseInt(depthRaw, 10);
+	if (!Number.isFinite(depth)) return undefined;
+	return { taskId, agentType, parentSessionId, rootSessionId, depth };
+}
diff --git a/src/runtime/in-process-runner.ts b/src/runtime/in-process-runner.ts
@@ -8,6 +8,7 @@ import {
 } from "@mariozechner/pi-coding-agent";
 import { loadAllAgents } from "../agents/loader.js";
 import type { AgentInfo } from "../agents/schema.js";
+import { clearInProcessAncestry, registerInProcessAncestry } from "./ancestry.js";
 import type { RunnerInput, RunnerResult, TaskRunner } from "./task-manager.js";
 
 type TextBlock = {
@@ -130,6 +131,13 @@ export class InProcessRunner implements TaskRunner {
 		const agents = await this.#loadAgents(cwd);
 		const agent = agents[input.task.agentType] ?? agents.default;
 		const session = await this.#createSession({ cwd, ...(model !== undefined && { model }) });
+		registerInProcessAncestry(session.sessionId, {
+			taskId: input.task.taskId,
+			agentType: input.task.agentType,
+			parentSessionId: input.task.parentSessionId,
+			rootSessionId: input.task.rootSessionId,
+			depth: input.task.depth,
+		});
 		let aborted = false;
 		const abort = (): void => {
 			aborted = true;
@@ -160,6 +168,7 @@ export class InProcessRunner implements TaskRunner {
 			};
 		} finally {
 			session.dispose?.();
+			clearInProcessAncestry(session.sessionId);
 		}
 	}
 }
diff --git a/src/runtime/process-runner.ts b/src/runtime/process-runner.ts
@@ -5,6 +5,10 @@ export type ProcessRunnerEvent = { type: "started"; pid: number } | { type: "std
 
 export type ProcessRunnerInput = {
 	taskId: string;
+	agentType?: string;
+	parentSessionId?: string;
+	rootSessionId?: string;
+	depth?: number;
 	command: string;
 	args: string[];
 	cwd?: string;
@@ -29,6 +33,11 @@ export class ProcessRunner {
 				env: {
 					...process.env,
 					PI_TASK_ID: input.taskId,
+					...(input.agentType !== undefined && { PI_TASK_AGENT_TYPE: input.agentType }),
+					...(input.parentSessionId !== undefined && { PI_TASK_PARENT_SESSION_ID: input.parentSessionId }),
+					...(input.rootSessionId !== undefined && { PI_TASK_ROOT_SESSION_ID: input.rootSessionId }),
+					...(input.depth !== undefined && { PI_TASK_DEPTH: String(input.depth) }),
+					PI_TASK_PARENT_TASK_ID: input.taskId,
 				},
 				stdio: ["ignore", "pipe", "pipe"],
 				shell: false,
diff --git a/src/runtime/process-task-runner.ts b/src/runtime/process-task-runner.ts
@@ -103,6 +103,10 @@ export class ProcessTaskRunner implements TaskRunner {
 			args: invocation.args,
 			cwd,
 			taskId: input.task.taskId,
+			agentType: input.task.agentType,
+			parentSessionId: input.task.parentSessionId,
+			rootSessionId: input.task.rootSessionId,
+			depth: input.task.depth,
 			signal: input.signal,
 		} satisfies ProcessRunnerInput);
 		return mapProcessResult(result);
diff --git a/src/runtime/task-manager.ts b/src/runtime/task-manager.ts
@@ -29,6 +29,7 @@ export type StartTaskInput = {
 	description?: string;
 	parentSessionId: string;
 	rootSessionId?: string;
+	parentAgentType?: string;
 	cwd?: string;
 	depth?: number;
 	model?: string;
@@ -111,6 +112,7 @@ export class TaskManager {
 			...(input.description !== undefined && { description: input.description }),
 			parentSessionId: input.parentSessionId,
 			rootSessionId: input.rootSessionId ?? input.parentSessionId,
+			...(input.parentAgentType !== undefined && { parentAgentType: input.parentAgentType }),
 			...(input.cwd !== undefined && { cwd: input.cwd }),
 			depth: input.depth ?? 0,
 			executionMode: input.executionMode ?? "in-process",
diff --git a/src/runtime/task-policy.ts b/src/runtime/task-policy.ts
@@ -0,0 +1,43 @@
+import type { AgentInfo } from "../agents/schema.js";
+import { evaluate, isSubagentAllowed } from "../permissions/rules.js";
+import type { TaskAncestry } from "./ancestry.js";
+
+const DEFAULT_MAX_DEPTH = 1;
+
+export type TaskPolicyDecision =
+	| { allowed: true; reason: "top-level" | "depth" | "allowed-subagent" | "permission" }
+	| { allowed: false; reason: string };
+
+export function decideTaskPolicy(input: {
+	targetAgentType: string;
+	ancestry?: TaskAncestry;
+	parentAgent?: AgentInfo;
+	maxDepth?: number;
+}): TaskPolicyDecision {
+	const childDepth = (input.ancestry?.depth ?? 0) + 1;
+	const parentAgent = input.parentAgent;
+
+	if (parentAgent?.allowedSubagents.includes(input.targetAgentType)) {
+		return { allowed: true, reason: "allowed-subagent" };
+	}
+
+	if (parentAgent !== undefined) {
+		const specific = evaluate(`task:${input.targetAgentType}`, "*", parentAgent.permission);
+		if (specific.action === "deny") {
+			return { allowed: false, reason: `Parent agent ${parentAgent.name} denies task:${input.targetAgentType}.` };
+		}
+		if (specific.action === "allow" || isSubagentAllowed(input.targetAgentType, parentAgent.permission)) {
+			return { allowed: true, reason: "permission" };
+		}
+	}
+
+	const maxDepth = parentAgent?.maxDepth ?? input.maxDepth ?? DEFAULT_MAX_DEPTH;
+	if (childDepth <= maxDepth) {
+		return { allowed: true, reason: input.ancestry === undefined ? "top-level" : "depth" };
+	}
+
+	return {
+		allowed: false,
+		reason: `Task nesting depth ${childDepth} exceeds maxDepth ${maxDepth} for ${input.targetAgentType}.`,
+	};
+}
diff --git a/src/runtime/task-state.ts b/src/runtime/task-state.ts
@@ -48,6 +48,7 @@ export function createTaskRecord(input: CreateTaskRecordInput): TaskRecord {
 		rootSessionId: input.rootSessionId,
 		...(input.childSessionId !== undefined && { childSessionId: input.childSessionId }),
 		...(input.cwd !== undefined && { cwd: input.cwd }),
+		...(input.parentAgentType !== undefined && { parentAgentType: input.parentAgentType }),
 		depth: input.depth,
 		executionMode: input.executionMode,
 		...(input.pid !== undefined && { pid: input.pid }),
diff --git a/src/runtime/types.ts b/src/runtime/types.ts
diff --git a/src/tools/task.ts b/src/tools/task.ts
diff --git a/test/agents/code-agents.test.ts b/test/agents/code-agents.test.ts
diff --git a/test/runtime/task-policy.test.ts b/test/runtime/task-policy.test.ts
diff --git a/test/tools/task.test.ts b/test/tools/task.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "pi-task",`
`3`		`- "version": "0.1.0",`
	`3`	`+ "version": "0.1.1",`
`4`	`4`	`"description": "Task subagent extension for the pi coding agent with background lifecycle visibility, resume, process supervision, and final-result retrieval.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"license": "MIT",`