feat: agent tool-boundary fields

.agentplane/agents/CODER.json

@@ -25,5 +25,8 @@
     "Prefer declared verify commands; record ad-hoc results via PR notes or request PLANNER to update verify lists.",
     "Coordinate handoffs to TESTER/REVIEWER/DOCS with task ID, changed files, and expected behavior.",
     "Avoid task closure in branch_pr; keep commits task-scoped and update status via `node packages/agentplane/bin/agentplane.js`."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

.agentplane/agents/CREATOR.json

@@ -21,5 +21,8 @@
     "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow.",
     "Update AGENTS.md registry guidance as needed and refresh any derived lists per spec.",
     "Validate JSON and update task status via `node packages/agentplane/bin/agentplane.js`; commit via `node packages/agentplane/bin/agentplane.js`."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

.agentplane/agents/DOCS.json

@@ -21,5 +21,8 @@
     "Update user/developer docs minimally to reflect behavior and match existing tone.",
     "Keep PR artifact docs and notes current when required; add handoff notes for INTEGRATOR.",
     "Avoid extra commits unless the task is doc-only."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "task_manage"],
+  "denied_tools": ["bash", "git_push"],
+  "model_preference": "balanced"
 }

.agentplane/agents/INTEGRATOR.json

@@ -24,5 +24,8 @@
     "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "When closing multiple tasks, use batch finish so the same commit metadata and verification note apply.",
     "Check `closure_commit_requires_approval` in .agentplane/config.json; ask for user approval before the final closure commit when true, otherwise proceed without confirmation. Optionally clean task branches/worktrees after closure."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "git_commit", "git_push", "task_manage"],
+  "denied_tools": [],
+  "model_preference": "powerful"
 }

.agentplane/agents/ORCHESTRATOR.json

@@ -28,5 +28,8 @@
     "Execute step by step and summarize task IDs plus commit hashes after each major step.",
     "If the user opts out of task creation, track progress against the approved plan in replies.",
     "Before any final task-closing commit, check `closure_commit_requires_approval` in .agentplane/config.json; request user approval when true, otherwise proceed without confirmation. Finalize with a concise summary and next steps."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "fast"
 }

.agentplane/agents/PLANNER.json

@@ -25,5 +25,8 @@
     "Create new tasks via task new (reserve task add for pre-existing IDs); include at least one tag and keep tags minimal.",
     "Scaffold task artifacts via `node packages/agentplane/bin/agentplane.js` when creating tasks; return a structured summary of touched IDs and status changes.",
     "Provide a numbered plan in replies when work spans multiple steps."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

.agentplane/agents/REDMINE.json

@@ -22,5 +22,8 @@
     "Inspect/update tasks and docs via `node packages/agentplane/bin/agentplane.js`; avoid direct API calls.",
     "Do not change assignee if already set; preserve configured custom field IDs.",
     "Push updates via `node packages/agentplane/bin/agentplane.js` sync redmine --direction push when required; add handoff notes if needed."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "fast"
 }

.agentplane/agents/REVIEWER.json

@@ -18,5 +18,8 @@
     "Prefer PR artifact review when present (README completeness, diffstat, verify log).",
     "Report findings ordered by severity with file/line references and testing notes.",
     "Record handoff notes via `node packages/agentplane/bin/agentplane.js`; do not integrate or finish tasks."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

.agentplane/agents/TESTER.json

@@ -24,5 +24,8 @@
     "Run targeted tests first and summarize only the key output lines.",
     "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "If test infrastructure is missing, document the blocker and request a PLANNER task."
-  ]
+  ],
+  "allowed_tools": ["read", "bash", "task_manage"],
+  "denied_tools": ["write", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

.agentplane/agents/UPDATER.json

@@ -19,5 +19,8 @@
     "Confirm the user explicitly summoned UPDATER; otherwise hand control back to ORCHESTRATOR.",
     "Audit AGENTS.md and .agentplane/agents/*.json plus relevant repo files, citing exact paths.",
     "Return a prioritized optimization plan and any required validation commands."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "balanced"
 }

.agentplane/agents/UPGRADER.json

@@ -23,5 +23,8 @@
     "Invoke `node packages/agentplane/bin/agentplane.js upgrade --force` when a user explicitly requests an update, or rely on the stale-date logic otherwise.",
     "Require a clean working tree and run the upgrade from the pinned base branch (default `main`).",
     "After a successful upgrade, update `framework.last_update` to `datetime.now(UTC).date()` and document the run in the owning task/pr artifacts."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "git_commit", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

packages/agentplane/assets/agents/CODER.json

@@ -25,5 +25,8 @@
     "Prefer declared verify commands; record ad-hoc results via PR notes or request PLANNER to update verify lists.",
     "Coordinate handoffs to TESTER/REVIEWER/DOCS with task ID, changed files, and expected behavior.",
     "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

packages/agentplane/assets/agents/CREATOR.json

@@ -21,5 +21,8 @@
     "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow.",
     "Update AGENTS.md registry guidance as needed and refresh any derived lists per spec.",
     "Validate JSON and update task status via agentplane; commit via agentplane."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

packages/agentplane/assets/agents/DOCS.json

@@ -21,5 +21,8 @@
     "Update user/developer docs minimally to reflect behavior and match existing tone.",
     "Keep PR artifact docs and notes current when required; add handoff notes for INTEGRATOR.",
     "Avoid extra commits unless the task is doc-only."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "task_manage"],
+  "denied_tools": ["bash", "git_push"],
+  "model_preference": "balanced"
 }

packages/agentplane/assets/agents/INTEGRATOR.json

@@ -24,5 +24,8 @@
     "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "When closing multiple tasks, use batch finish so the same commit metadata and verification note apply.",
     "Check `closure_commit_requires_approval` in .agentplane/config.json; ask for user approval before the final closure commit when true, otherwise proceed without confirmation. Optionally clean task branches/worktrees after closure."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "git_commit", "git_push", "task_manage"],
+  "denied_tools": [],
+  "model_preference": "powerful"
 }

packages/agentplane/assets/agents/ORCHESTRATOR.json

@@ -28,5 +28,8 @@
     "Execute step by step and summarize task IDs plus commit hashes after each major step.",
     "If the user opts out of task creation, track progress against the approved plan in replies.",
     "Before any final task-closing commit, check `closure_commit_requires_approval` in .agentplane/config.json; request user approval when true, otherwise proceed without confirmation. Finalize with a concise summary and next steps."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "fast"
 }

packages/agentplane/assets/agents/PLANNER.json

@@ -25,5 +25,8 @@
     "Create new tasks via task new (reserve task add for pre-existing IDs); include at least one tag and keep tags minimal.",
     "Scaffold task artifacts via agentplane when creating tasks; return a structured summary of touched IDs and status changes.",
     "Provide a numbered plan in replies when work spans multiple steps."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

packages/agentplane/assets/agents/REDMINE.json

@@ -22,5 +22,8 @@
     "Inspect/update tasks and docs via agentplane; avoid direct API calls.",
     "Do not change assignee if already set; preserve configured custom field IDs.",
     "Push updates via agentplane sync redmine --direction push when required; add handoff notes if needed."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "bash", "git_commit", "git_push"],
+  "model_preference": "fast"
 }

packages/agentplane/assets/agents/REVIEWER.json

@@ -18,5 +18,8 @@
     "Prefer PR artifact review when present (README completeness, diffstat, verify log).",
     "Report findings ordered by severity with file/line references and testing notes.",
     "Record handoff notes via agentplane; do not integrate or finish tasks."
-  ]
+  ],
+  "allowed_tools": ["read", "task_manage"],
+  "denied_tools": ["write", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

packages/agentplane/assets/agents/TESTER.json

@@ -24,5 +24,8 @@
     "Run targeted tests first and summarize only the key output lines.",
     "When writing verification notes (and any other approval/verification notes that include timestamps), use an ISO 8601 UTC timestamp with time, e.g. 2026-02-07T16:20:02.717Z; avoid date-only values like 2026-02-07.",
     "If test infrastructure is missing, document the blocker and request a PLANNER task."
-  ]
+  ],
+  "allowed_tools": ["read", "bash", "task_manage"],
+  "denied_tools": ["write", "git_commit", "git_push"],
+  "model_preference": "balanced"
 }

packages/agentplane/assets/agents/UPDATER.json

@@ -19,5 +19,8 @@
     "Confirm the user explicitly summoned UPDATER; otherwise hand control back to ORCHESTRATOR.",
     "Audit AGENTS.md and .agentplane/agents/*.json plus relevant repo files, citing exact paths.",
     "Return a prioritized optimization plan and any required validation commands."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "balanced"
 }

packages/agentplane/assets/agents/UPGRADER.json

@@ -23,5 +23,8 @@
     "Invoke `agentplane upgrade --force` when a user explicitly requests an update, or rely on the stale-date logic otherwise.",
     "Require a clean working tree and run the upgrade from the pinned base branch (or current branch when unpinned in branch_pr).",
     "After a successful upgrade, update `framework.last_update` to `datetime.now(UTC).date()` and document the run in the owning task/pr artifacts."
-  ]
+  ],
+  "allowed_tools": ["read", "write", "bash", "git_commit", "task_manage"],
+  "denied_tools": ["git_push"],
+  "model_preference": "powerful"
 }

packages/agentplane/src/cli/run-cli/registry.ts

@@ -173,6 +173,8 @@ import {
 } from "../../commands/guard/suggest-allow.command.js";
 import { guardCommitSpec, makeRunGuardCommitHandler } from "../../commands/guard/commit.command.js";
 
+import { agentLintSpec, runAgentLint } from "../../commands/agent/lint.command.js";
+
 import type { CommandContext } from "../../commands/shared/task-backend.js";
 
 const helpNoop = () => Promise.resolve(0);
@@ -184,6 +186,7 @@ export function buildHelpFastRegistry(): CommandRegistry {
   registry.register(quickstartSpec, helpNoop);
   registry.register(roleSpec, helpNoop);
   registry.register(agentsSpec, helpNoop);
+  registry.register(agentLintSpec, helpNoop);
   registry.register(configShowSpec, helpNoop);
   registry.register(configSetSpec, helpNoop);
   registry.register(modeGetSpec, helpNoop);
@@ -277,6 +280,7 @@ export function buildRegistry(
   registry.register(quickstartSpec, runQuickstart);
   registry.register(roleSpec, runRole);
   registry.register(agentsSpec, runAgents);
+  registry.register(agentLintSpec, runAgentLint);
   registry.register(configShowSpec, runConfigShow);
   registry.register(configSetSpec, runConfigSet);
   registry.register(modeGetSpec, runModeGet);

packages/agentplane/src/commands/agent/lint.command.ts

@@ -0,0 +1,17 @@
+import type { CommandCtx, CommandSpec } from "../../cli/spec/spec.js";
+
+import { cmdAgentLint } from "./lint.js";
+
+export type AgentLintParsed = Record<string, never>;
+
+export const agentLintSpec: CommandSpec<AgentLintParsed> = {
+  id: ["agent", "lint"],
+  group: "Agent",
+  summary: "Lint agent JSON definitions (schema + invariants).",
+  examples: [{ cmd: "agentplane agent lint", why: "Validate all agent definitions." }],
+  parse: () => ({}),
+};
+
+export async function runAgentLint(ctx: CommandCtx): Promise<number> {
+  return await cmdAgentLint({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });
+}

packages/agentplane/src/commands/agent/lint.ts

@@ -0,0 +1,35 @@
+import { lintAgentsDir, loadConfig, resolveProject } from "@agentplaneorg/core";
+import path from "node:path";
+
+import { mapCoreError } from "../../cli/error-map.js";
+import { CliError } from "../../shared/errors.js";
+
+export async function cmdAgentLint(opts: {
+  cwd: string;
+  rootOverride?: string;
+}): Promise<number> {
+  try {
+    const resolved = await resolveProject({
+      cwd: opts.cwd,
+      rootOverride: opts.rootOverride ?? null,
+    });
+    const loaded = await loadConfig(resolved.agentplaneDir);
+    const agentsDir = path.join(resolved.gitRoot, loaded.config.paths.agents_dir);
+    const result = await lintAgentsDir(agentsDir);
+    if (result.errors.length > 0) {
+      throw new CliError({
+        exitCode: 3,
+        code: "E_VALIDATION",
+        message: result.errors.join("\n"),
+      });
+    }
+    for (const w of result.warnings) {
+      process.stderr.write(`warn: ${w}\n`);
+    }
+    process.stdout.write("OK\n");
+    return 0;
+  } catch (err) {
+    if (err instanceof CliError) throw err;
+    throw mapCoreError(err, { command: "agent lint", root: opts.rootOverride ?? null });
+  }
+}

packages/core/schemas/agent.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agentplane.dev/schemas/agent.schema.json",
+  "title": "agentplane agent definition",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["id", "role", "description", "permissions", "workflow"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[A-Z][A-Z0-9_]*$",
+      "minLength": 1
+    },
+    "role": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "inputs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "outputs": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "permissions": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "workflow": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
+    },
+    "allowed_tools": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "denied_tools": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "model_preference": {
+      "type": "string",
+      "enum": ["fast", "balanced", "powerful"]
+    }
+  }
+}