ap-policies

Completion Policies

When to use

Use ap-policies to gate a session (or fan-in group) at turn-end by an objective check — a shell command's exit code or a judge sub-agent's verdict — instead of trusting the agent's own "done" claim, and/or to auto-commit once that gate is green, pending an explicit human ack.

MCP tool: policy_attach

Attach a gate to one sessionId, or a sessionIds array for a fan-in group (the policy resolves once ALL sessions in the group reach turn-end). The gate is either a shell command (basename must be allowlisted, see ap-run-command) or a judge adapter + prompt. then decides what happens on pass: emit (just publish policy:passed) or commit (stage + commit specific paths, gated by requireHumanAck). onFail controls retries with a nudge prompt. next chains another policy as a DAG.

{
  "tool": "policy_attach",
  "args": {
    "sessionIds": ["sess_a1b2", "sess_c3d4"],
    "gate": { "command": { "name": "pnpm", "args": ["test:unit"] } },
    "then": "commit",
    "commit": {
      "paths": ["services/api-gateway/src/routes/webhook.ts"],
      "message": "fix: validate webhook signature before dispatch",
      "requireHumanAck": true
    },
    "onFail": { "nudge": "tests still red — fix the failing assertions", "maxRetries": 3 }
  }
}

Judge gate variant:

{
  "tool": "policy_attach",
  "args": {
    "sessionId": "sess_a1b2",
    "gate": {
      "judge": {
        "adapter": "claude-code",
        "prompt": "Does the diff add a test for the new webhook signature check? Answer pass/fail with one reason."
      }
    },
    "then": "emit"
  }
}

MCP tools: policy_status / policy_list

policy_status polls state (pending | passed | failed | awaiting_ack) plus awaitingQuestions — judge follow-ups blocking resolution. policy_list lists active/recent policies, optionally filtered by sessionId.

{ "tool": "policy_status", "args": { "policyId": "pol_9f21" } }
{ "tool": "policy_list", "args": { "sessionId": "sess_a1b2" } }