tx auto guard

Set task creation limits to prevent unbounded proliferation

Purpose

tx auto guard sets limits on task creation to prevent unbounded proliferation. Guards are checked every time tx add creates a task.

Guards support two modes:

Advisory (default): Tasks are created with warnings. Agents see the warning and can self-correct.
Enforce: tx add fails with GuardExceededError when limits are exceeded.

Usage

tx auto guard set [options]
tx auto guard show [--json]
tx auto guard clear [--scope <scope>]

# Set global limits (advisory mode)
tx auto guard set --max-pending 50 --max-children 10 --max-depth 4

# Enable enforcement
tx auto guard set --max-pending 30 --enforce

# Scope limits to a parent task
tx auto guard set --scope parent:tx-abc123 --max-children 5

# Show current guards
tx auto guard show

# Clear all guards
tx auto guard clear

import { TxClient } from '@jamesaphoenix/tx-agent-sdk'

const tx = new TxClient({ dbPath: '.tx/tasks.db' })

// Set guard limits
await tx.guards.set({
  maxPending: 50,
  maxChildren: 10,
  maxDepth: 4,
  enforce: true,
})

// Show current guards
const guards = await tx.guards.show()

// Check if creation would be allowed
const result = await tx.guards.check({ parentId: 'tx-abc123' })
// { passed: true, warnings: [] }

// Clear guards
await tx.guards.clear()

Tool name: tx_auto_guard_set

{
  "name": "tx_auto_guard_set",
  "arguments": {
    "scope": "global",
    "maxPending": 50,
    "maxChildren": 10,
    "maxDepth": 4,
    "enforce": true
  }
}

Arg	Type	Required	Description
`scope`	`string`	No	Guard scope: 'global' or 'parent:<task-id>'
`maxPending`	`number`	No	Maximum non-done tasks
`maxChildren`	`number`	No	Maximum children per parent
`maxDepth`	`number`	No	Maximum hierarchy nesting depth
`enforce`	`boolean`	No	true = hard block, false = advisory

Other tools: tx_auto_guard_show, tx_auto_guard_clear, tx_auto_guard_check

{
  "name": "tx_auto_guard_check",
  "arguments": {
    "parentId": "tx-abc123"
  }
}

POST /api/guards
GET  /api/guards
GET  /api/guards/check?parentId=tx-abc123
DELETE /api/guards?scope=global

Example:

# Set guard limits
curl -X POST http://localhost:3456/api/guards \
  -H 'Content-Type: application/json' \
  -d '{"maxPending": 50, "maxChildren": 10, "enforce": true}'

# Check if creation allowed
curl http://localhost:3456/api/guards/check

Options

Option	Description
`--max-pending <n>`	Maximum non-done tasks at any time
`--max-children <n>`	Maximum direct children per parent
`--max-depth <n>`	Maximum hierarchy nesting depth
`--enforce`	Enable hard blocking (default: advisory)
`--scope <scope>`	Guard scope: 'global' or 'parent:<task-id>'
`--json`	Output as JSON

Advisory vs Enforce Mode

Mode	Behavior
Advisory (default)	Tasks are created. Warning metadata is added. Stderr shows warning.
Enforce	`tx add` fails with `GuardExceededError`. Task is NOT created.

Recommended workflow: Deploy advisory first, observe patterns with tx auto reflect, then tighten limits and enable enforcement.

Configuration

Guards can be configured in .tx/config.toml:

[guard]
mode = "advisory"     # "advisory" or "enforce"
# max_pending = 50
# max_children = 10
# max_depth = 4

Agent Loop Pattern

#!/bin/bash
# Set up guardrails before starting agent loop
tx auto guard set --max-pending 30 --max-depth 3 --enforce

while task=$(tx ready --json --limit 1 | jq -r '.[0].id // empty'); do
  [ -z "$task" ] && break
  claude "Work on $task. Run tx done $task when complete."
done

tx auto gate: Human approval checkpoints between phases
tx auto reflect: Analyze session metrics to tune guard limits
tx ready: Get next workable task
tx auto verify: Attach machine-checkable done criteria
tx auto label: Scope the ready queue by phase