agent-claude.kdl

// Canonical hand-authored declaration for a Claude Code agent. It keeps the persona and native bus
// contract in a catalog-owned `.st2/` overlay and adds a small Claude rules loader.

agent "<identity>" {
  host "<host>"
  workspace "<workspace>"
  // Optional metadata:
  // role "worker"
  // supervisor "<host>.<supervisor-identity>"

  // The rendered bus contract requires agent-declared status: busy while executing work, available
  // only when yielding/ready, and dnd only for an explicit hold.
  argv "claude" "--permission-mode" "bypassPermissions" "<boot prompt>"
  ding

  render {
    copy "assets/PERSONA.md" ".st2/PERSONA.md"
    copy "assets/bus.st2.md" ".st2/bus.md"
    ensure-line ".claude/rules/st2.md" "@../../.st2/PERSONA.md"
    ensure-line ".claude/rules/st2.md" "@../../.st2/bus.md"
    // Hooks-only observability: this seat launches claude directly (no session wrapper), so the
    // registrations below give it transitions and blocked-on-you — but no heartbeat owner and no
    // terminal record. A live-but-idle seat ages to `unknown` after the staleness horizon and an
    // exit leaves the last state to age out; both read indeterminate, never wrong. The full
    // producer (heartbeats, terminal exits) comes with the session wrapper, i.e. a typed
    // `claude {}` driver seat or `deliver "mcp"`.
    //
    // The `statusLine` entry is the harness-context tee: it is Claude's ONLY channel carrying a
    // context window, and the slot is single-valued — the winning declaration replaces the others
    // outright rather than merging. So this command records the payload and then chains to the
    // operator's own renderer, resolved from `$ST_CLAUDE_STATUSLINE_RENDERER` or
    // `~/.claude/statusline-renderer.json`, passing the payload through unchanged when neither
    // resolves. Declaring anything else here would silently remove the operator's status line.
    json-upsert ".claude/settings.local.json" arrays="union" #"""
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "async": true,
            "asyncRewake": true,
            "command": "\"$ST_HOOKS/claude-session-start.sh\""
          },
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" SessionStart"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-pre-compact.sh\""
          },
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" PreCompact"
          }
        ]
      }
    ],
    "PostCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" PostCompact"
          }
        ]
      }
    ],
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-stop-failure.sh\""
          },
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" StopFailure"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" UserPromptSubmit"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" Stop"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" PermissionRequest"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$ST_HOOKS/claude-observe.sh\" PostToolUse"
          }
        ]
      }
    ]
  },
  "statusLine": {
    "type": "command",
    "command": "\"$ST_HOOKS/claude-statusline.sh\"",
    "padding": 0,
    "refreshInterval": 5
  }
}
"""#
    git-exclude ".st2/" ".claude/rules/st2.md" ".claude/settings.local.json"
  }
}