cal/claude-home
1
0
Fork 0
Code Issues 6 Pull Requests 4 Actions Packages Projects Releases Wiki Activity

headless-claude: Additional Agent SDK improvements #3

New Issue
Closed
opened 2026-03-01 14:02:55 +00:00 by cal · 1 comment
cal commented 2026-03-01 14:02:55 +00:00
Owner
Copy Link

Context

Project: /mnt/NV2/Development/headless-claude/

After reviewing the updated Claude Code Agent SDK documentation, we identified several improvement opportunities beyond the two already implemented (--json-schema for structured output and tighter --allowedTools prefix matching).

Recommendations

1. Use --append-system-prompt for role injection

Rather than relying entirely on the skill's SKILL.md being auto-loaded, inject critical context directly into the system prompt:

--append-system-prompt "You are a server diagnostics agent. Use the server-diagnostics skill client.py for all operations. Never run destructive commands."

This ensures consistent behavior regardless of skill loading order and provides a safety net.

2. Session resumption for escalation workflows

Use --resume <session_id> to continue diagnostic conversations across invocations. This enables:

  • Sending follow-up prompts in the same context (e.g., "now check the logs for that container")
  • Reducing cost by avoiding re-discovery on related alerts
  • Building multi-step escalation workflows in n8n

Pattern:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

3. Evaluate the Python/TypeScript Agent SDK

The docs now offer native Python/TypeScript packages (from claude_code import Claude) as an alternative to CLI invocation. If n8n's Code node or a custom n8n node is ever used, this would be cleaner than SSH-to-CLI shell invocation and offers:

  • Structured message objects
  • Tool approval callbacks
  • Native streaming support

Reference: https://platform.claude.com/docs/en/agent-sdk/overview

Priority

Medium — current system works well. These are quality-of-life improvements for Phase 2/3.

## Context Project: `/mnt/NV2/Development/headless-claude/` After reviewing the updated [Claude Code Agent SDK documentation](https://code.claude.com/docs/en/headless), we identified several improvement opportunities beyond the two already implemented (`--json-schema` for structured output and tighter `--allowedTools` prefix matching). ## Recommendations ### 1. Use `--append-system-prompt` for role injection Rather than relying entirely on the skill's `SKILL.md` being auto-loaded, inject critical context directly into the system prompt: ```bash --append-system-prompt "You are a server diagnostics agent. Use the server-diagnostics skill client.py for all operations. Never run destructive commands." ``` This ensures consistent behavior regardless of skill loading order and provides a safety net. ### 2. Session resumption for escalation workflows Use `--resume <session_id>` to continue diagnostic conversations across invocations. This enables: - Sending follow-up prompts in the same context (e.g., "now check the logs for that container") - Reducing cost by avoiding re-discovery on related alerts - Building multi-step escalation workflows in n8n Pattern: ```bash session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id') claude -p "Continue that review" --resume "$session_id" ``` ### 3. Evaluate the Python/TypeScript Agent SDK The docs now offer native Python/TypeScript packages (`from claude_code import Claude`) as an alternative to CLI invocation. If n8n's Code node or a custom n8n node is ever used, this would be cleaner than SSH-to-CLI shell invocation and offers: - Structured message objects - Tool approval callbacks - Native streaming support Reference: https://platform.claude.com/docs/en/agent-sdk/overview ## Priority Medium — current system works well. These are quality-of-life improvements for Phase 2/3.
cal commented 2026-04-03 19:34:33 +00:00
Author
Owner
Copy Link

Implementation Status

Recommendation 1: --append-system-prompt for role injection

Status: Already implemented ✅

This is already in production use across all live claude-scheduled scripts:

  • runner.sh:105 — injects task name and date context
  • issue-poller.sh:299,674 — injects autonomous worker role
  • pr-reviewer-dispatcher.sh:327 — injects reviewer role

The legacy n8n workflow has also been updated to include --append-system-prompt in the SSH invocation node.

Recommendation 2: Session resumption with --resume

Status: Implemented ✅

runner.sh — Opt-in session persistence via two new settings.json fields:

  • session_resumable: true — enables session persistence and saves session_id to $LOG_DIR/last_session_id
  • resume_last_session: true — resumes the previous session on the next run via --resume
  • Default behavior unchanged (--no-session-persistence)

issue-poller.sh — Captures session_id from worker output and includes it in:

  • Log lines (session_id=...)
  • Result JSON for each processed issue/PR

pr-reviewer-dispatcher.sh — Same pattern: captures and logs session_id.

n8n workflow — Added two new nodes:

  • "Follow Up Diagnostics" SSH node that resumes the session with --resume for deeper investigation when issues are found
  • "Parse Follow-up Response" Code node that merges follow-up data with initial findings
  • Discord Alert updated to show detailed root cause and remediation steps from follow-up

Recommendation 3: Evaluate Python/TypeScript Agent SDK

Status: Evaluation complete ✅

Research document written at scheduled-tasks/agent-sdk-evaluation.md.

Recommendation: Stay with CLI invocation for now.

Key blocker: The SDK requires ANTHROPIC_API_KEY (per-token billing), while our entire framework runs on Claude Max OAuth at zero marginal cost. The CLI now covers all our needs with --append-system-prompt, --resume, --json-schema, and --allowedTools.

Revisit when: OAuth support is added to the SDK, or we need dynamic tool approval / in-process hooks.

Branch: feature/3-agent-sdk-improvements

## Implementation Status ### Recommendation 1: `--append-system-prompt` for role injection **Status: Already implemented** ✅ This is already in production use across all live claude-scheduled scripts: - `runner.sh:105` — injects task name and date context - `issue-poller.sh:299,674` — injects autonomous worker role - `pr-reviewer-dispatcher.sh:327` — injects reviewer role The legacy n8n workflow has also been updated to include `--append-system-prompt` in the SSH invocation node. ### Recommendation 2: Session resumption with `--resume` **Status: Implemented** ✅ **runner.sh** — Opt-in session persistence via two new `settings.json` fields: - `session_resumable: true` — enables session persistence and saves `session_id` to `$LOG_DIR/last_session_id` - `resume_last_session: true` — resumes the previous session on the next run via `--resume` - Default behavior unchanged (`--no-session-persistence`) **issue-poller.sh** — Captures `session_id` from worker output and includes it in: - Log lines (`session_id=...`) - Result JSON for each processed issue/PR **pr-reviewer-dispatcher.sh** — Same pattern: captures and logs `session_id`. **n8n workflow** — Added two new nodes: - "Follow Up Diagnostics" SSH node that resumes the session with `--resume` for deeper investigation when issues are found - "Parse Follow-up Response" Code node that merges follow-up data with initial findings - Discord Alert updated to show detailed root cause and remediation steps from follow-up ### Recommendation 3: Evaluate Python/TypeScript Agent SDK **Status: Evaluation complete** ✅ Research document written at `scheduled-tasks/agent-sdk-evaluation.md`. **Recommendation: Stay with CLI invocation for now.** Key blocker: The SDK requires `ANTHROPIC_API_KEY` (per-token billing), while our entire framework runs on Claude Max OAuth at zero marginal cost. The CLI now covers all our needs with `--append-system-prompt`, `--resume`, `--json-schema`, and `--allowedTools`. Revisit when: OAuth support is added to the SDK, or we need dynamic tool approval / in-process hooks. --- Branch: `feature/3-agent-sdk-improvements`
cal closed this issue 2026-04-03 20:00:14 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels   
ai-changes-requested

   
ai-failed

   
ai-pr-opened

   
ai-reviewed

   
ai-reviewing

   
ai-working

   
infra-audit

Infrastructure audit remediation tasks

  
monitoring

Monitoring, alerting, and observability

  
operations

Ongoing operational improvements

  
proxmox

Proxmox VM/CT management

  
script

Script improvements and tooling

No Label
ai-changes-requested
ai-failed
ai-pr-opened
ai-reviewed
ai-reviewing
ai-working
infra-audit
monitoring
operations
proxmox
script
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: cal/claude-home#3
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?