Knowledge Ams Flags And Schemas

Knowledge: AMS Flags and Schemas for Claude Code

Overview

This skill documents the exact CLI flags and JSON schemas used by the Agent Management Server (AMS) to spawn and communicate with Claude Code agents. Use this when:

• Implementing agent spawning in tmux or subprocess
• Building stream-json SDK integrations
• Debugging agent startup or resume issues
• Understanding centralized logging configuration

Source of Truth: /Users/sotola/AgenticProjects/agent-box-v1/services/ams-tmux/

TUI Mode (Interactive)

AMS spawns Claude in TUI (Terminal User Interface) mode by default. This runs the interactive terminal interface.

Core Command

claude --dangerously-skip-permissions --log-dir <log_dir>

Required Flags

Optional Flags

AMS TUI Spawn Example

# Full command as spawned by AMS (from claude_tmux_spawner.py)
CLAUDE_CONFIG_DIR=~/.claude \
  ~/symlinks/claude \
    --dangerously-skip-permissions \
    --log-dir ~/centralized-logs/claude

tmux Wrapper

AMS wraps the command to keep tmux sessions alive for post-mortem debugging:

bash -lc 'set +e; \
  echo "[ams_tmux] start $(date -u +%Y-%m-%dT%H:%M:%SZ)"; \
  echo "[ams_tmux] cmd: <escaped_cmd>"; \
  echo "[ams_tmux] ---"; \
  <cmd>; \
  rc=$?; \
  echo "[ams_tmux] exit rc=$rc $(date -u +%Y-%m-%dT%H:%M:%SZ)"; \
  echo "[ams_tmux] keeping tmux session alive for post-mortem"; \
  while true; do sleep 3600; done'

SDK Mode (Programmatic / stream-json)

For programmatic control, Claude Code supports bidirectional JSON streaming via stdin/stdout.

Core Command

claude -p \
  --input-format stream-json \
  --output-format stream-json \
  --dangerously-skip-permissions \
  --log-dir <log_dir>

Required Flags for SDK Mode

Optional SDK Flags

Full SDK Mode Example

CLAUDE_CONFIG_DIR=~/.claude \
  node ~/symlinks/claude/cli.js \
    -p \
    --resume 757cc520-4b58-4827-9132-c6982d3f8aba \
    --input-format stream-json \
    --output-format stream-json \
    --dangerously-skip-permissions \
    --log-dir /tmp/agent-test

Input Schema (stdin)

Send JSON messages to stdin, one per line (JSONL format).

User Message

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      { "type": "text", "text": "Your prompt here" }
    ]
  }
}

User Message with Image

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      { "type": "text", "text": "Describe this image" },
      {
        "type": "image",
        "source": {
          "type": "base64",
          "media_type": "image/png",
          "data": "<base64_encoded_image>"
        }
      }
    ]
  }
}

Interrupt Request

{
  "type": "control_request",
  "request": {
    "subtype": "interrupt"
  }
}

Output Event Types (stdout)

Claude emits JSONL events on stdout. Parse each line as JSON.

message_start

Signals the beginning of a new assistant response.

{
  "type": "message_start",
  "message": {
    "id": "msg_...",
    "type": "message",
    "role": "assistant",
    "content": [],
    "model": "claude-sonnet-4-20250514",
    "stop_reason": null
  }
}

content_block_delta

Streaming content chunks (requires --include-partial-messages).

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "partial text..."
  }
}

content_block_stop

Marks the end of a content block.

{
  "type": "content_block_stop",
  "index": 0
}

message_stop

Signals the complete end of the assistant's response.

{
  "type": "message_stop"
}

assistant (Complete Message)

Full assistant message (when not using partial streaming).

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [
      { "type": "text", "text": "Full response text..." }
    ]
  }
}

tool_use

Agent is invoking a tool.

{
  "type": "tool_use",
  "id": "toolu_...",
  "name": "Bash",
  "input": {
    "command": "ls -la"
  }
}

tool_result

Result from a tool execution.

{
  "type": "tool_result",
  "tool_use_id": "toolu_...",
  "content": "command output..."
}

error

Error from the agent.

{
  "type": "error",
  "error": {
    "type": "invalid_request",
    "message": "Error description"
  }
}

result

Final result when conversation completes.

{
  "type": "result",
  "result": "Final output text..."
}

Environment Variables

Required by AMS

Optional / Debugging

AMS-Specific

Resume Sessions

Resume in TUI Mode

CLAUDE_CONFIG_DIR=~/.claude \
  claude --dangerously-skip-permissions \
         --log-dir ~/centralized-logs/claude \
         --resume <session_id>

Resume in SDK Mode

CLAUDE_CONFIG_DIR=~/.claude \
  claude -p \
         --input-format stream-json \
         --output-format stream-json \
         --dangerously-skip-permissions \
         --log-dir ~/centralized-logs/claude \
         --resume <session_id>

Fork on Resume (New SID)

claude --resume <session_id> --fork-session

Session File Location

Sessions are stored at:

$CLAUDE_CONFIG_DIR/projects/<hashed_cwd>/<session_id>.jsonl

Example:

~/.claude/projects/-Users-sotola-myproject/757cc520-4b58-4827-9132-c6982d3f8aba.jsonl

Complete Examples

1. Spawn Managed Agent (AMS Pattern)

import subprocess
import os

env = os.environ.copy()
env["CLAUDE_CONFIG_DIR"] = os.path.expanduser("~/.claude")

cmd = [
    os.path.expanduser("~/symlinks/claude"),
    "--dangerously-skip-permissions",
    "--log-dir", os.path.expanduser("~/centralized-logs/claude"),
]

# Spawn in tmux session
subprocess.run([
    "tmux", "new-session", "-d", "-s", "claude-agent-001",
    f"bash -lc '{' '.join(cmd)}; while true; do sleep 3600; done'"
], env=env)

2. SDK Mode Python Client

import json
import subprocess
import os

cmd = [
    "node",
    os.path.expanduser("~/symlinks/claude/cli.js"),
    "-p",
    "--input-format", "stream-json",
    "--output-format", "stream-json",
    "--dangerously-skip-permissions",
    "--log-dir", "/tmp/agent-sdk"
]

env = os.environ.copy()
env["CLAUDE_CONFIG_DIR"] = os.path.expanduser("~/.claude")

proc = subprocess.Popen(
    cmd,
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    env=env,
    text=True,
    bufsize=1
)

# Send a message
msg = {
    "type": "user",
    "message": {
        "role": "user",
        "content": [{"type": "text", "text": "Hello, Claude!"}]
    }
}
proc.stdin.write(json.dumps(msg) + "\n")
proc.stdin.flush()

# Read responses
for line in proc.stdout:
    event = json.loads(line)
    if event.get("type") == "message_stop":
        break
    print(event)

3. Resume with Debug Logging

cd /path/to/project && \
  CLAUDE_CONFIG_DIR=~/.claude \
  CLAUDE_CODE_REHYDRATE_DEBUG_JSONL=/tmp/resume-debug.jsonl \
  claude --resume 757cc520-4b58-4827-9132-c6982d3f8aba \
         --dangerously-skip-permissions \
         --log-dir ~/centralized-logs/claude

Session Naming Convention (tmux)

AMS uses this pattern for tmux session names:

agent-box-{provider}-{handler_id}-sid-{session_id}-pid-{process_id}

Example:

agent-box-claude-019b9e3b-d32d-7550-b219-25c88e730b21-sid-abc12345-def6-7890-ghij-klmn-pid-54321

Components

Troubleshooting

No Response from SDK Mode

1. Ensure -p flag is present (required for stream-json)
2. Check stderr for errors
3. Verify CLAUDE_CONFIG_DIR is writable
4. Confirm session file exists (for resume)

Resume Stalls

1. Set CLAUDE_CODE_REHYDRATE_DEBUG_JSONL to debug
2. Check session file exists at $CLAUDE_CONFIG_DIR/projects/<hashed_cwd>/<sid>.jsonl
3. Ensure cwd matches the original session's cwd

Session ID Not Found in Logs

1. Wait for claude.user_prompt or claude.session_start event (not claude.warmup)
2. Warmup emits a temporary SID - ignore it for session identity
3. Real SID appears in session boundary events