[EPIC] Open-Ended Delegation

[jsbattig]

[Conversation Reference: "Evolve CIDX delegation from template-locked pre-defined functions to open-ended delegation where any authenticated poweruser/admin can delegate any coding objective to Claude Server with multi-engine support and safety guardrails"]

Executive Summary

Epic Objective: Enable open-ended delegation through CIDX where authenticated power users and admins can submit any free-form coding objective to Claude Server, with configurable agent engines, execution modes, and safety guardrails managed via a dedicated golden repo convention.

Business Value: Removes the current template-locked limitation of the delegation system, allowing developers using Claude Code or claude.ai via MCP to leverage Claude Server's full capabilities for any coding objective without being restricted to pre-defined function templates.

Architecture Impact: Adds a new MCP tool (execute_open_delegation) alongside the existing execute_delegation_function (which remains unchanged), extends ClaudeServerClient with a new create_job_with_options() method, introduces a guardrails repo convention for safety and package authorization, and extends the Web UI config screen with delegation settings.

Epic Scope and Objectives

Primary Objectives

• Implement a single execute_open_delegation MCP tool that accepts free-form prompts with engine and mode selection
• Establish a guardrails repo convention for safety prompts and authorized package lists, with fallback to hardcoded defaults
• Expose delegation configuration (guardrails repo, default engine, default mode, guardrails toggle) in the CIDX Web UI
• Audit every open delegation call through existing AuditLogService infrastructure

Measured Success Criteria

• Power users and admins can submit any coding objective via execute_open_delegation and receive a job_id for polling
• Normal users receive "Access denied" when attempting open delegation
• Guardrails from a configured golden repo are automatically prepended to prompts
• When no guardrails repo is configured, hardcoded default guardrails with "install nothing external" are applied
• Collaborative and competitive modes return clear "Mode not yet supported" errors (no fallback, no dead code)
• All open delegation calls are logged in the audit trail with full context
• Web UI config screen allows setting guardrails repo, engine, mode, and guardrails toggle
• Existing template-based execute_delegation_function remains completely unchanged and functional

Architecture Overview

User (Claude Code / claude.ai via MCP)
         |
         v
  execute_open_delegation (MCP tool)
         |
         +-- Permission check (delegate_open)
         +-- Guardrails resolution
         |     +-- Golden repo configured? --> Load system-prompt.md + packages
         |     +-- No repo? --> DEFAULT_GUARDRAILS_TEMPLATE
         |     +-- guardrails_enabled=false? --> Skip
         +-- Repo readiness polling
         |     +-- GET /repositories/{name} on Claude Server
         |     +-- If missing: POST /repositories/register --> poll until cloneStatus="completed"
         |     +-- Timeout from existing golden repo registration config
         +-- Job creation via create_job_with_options()
         |     +-- single mode: POST /jobs (with JobOptionsDto)
         |     +-- collaborative: error "Mode not yet supported"
         |     +-- competitive: error "Mode not yet supported"
         +-- Callback registration: POST /jobs/{id}/callbacks
         +-- Job start: POST /jobs/{id}/start
         +-- Audit log via AuditLogService.log()
         |
         v
  Returns job_id --> poll via existing poll_delegation_job

Key Architectural Decisions

1. Single tool with mode parameter (not separate tools per mode) -- reduces tool proliferation, matches existing pattern
2. New create_job_with_options() method -- separate from existing create_job() for backward compatibility
3. Guardrails repo convention -- ONE golden repo controls both safety guardrails AND authorized packages; config stores only the repo alias pointer
4. Repo readiness polling -- CIDX polls Claude Server until repo clone completes before creating job; uses existing config timeout (not hardcoded)
5. Async polling model -- no streaming, no real-time; reuses existing poll_delegation_job for result retrieval
6. Safety model -- "no guardrails on objective, guardrails on harm" -- users can ask for anything, but the agent is constrained on what it can do to the system
7. Persistent MCP connect-back -- CIDX is registered as a persistent MCP server on Claude Server (not injected per-job). All jobs across all engines and modes have access to CIDX tools. The guardrails prompt instructs the agent to use CIDX to validate packages against the authorized packages repo.

Features and Stories Implementation Order

[Conversation Reference: "Implementation order: Story 1 -> Story 2 -> Story 4 -> Story 3"]

Feature 1: Open-Ended Job Delegation (feat:delegation-core)

[Conversation Reference: "Single MCP tool execute_open_delegation with mode parameter, new delegate_open permission, new create_job_with_options() on ClaudeServerClient, repo readiness polling"]

• #PENDING [STORY] Story 1: Open-ended delegation with engine and mode selection

Feature 2: Safety Guardrails System (feat:guardrails)

[Conversation Reference: "ONE golden repo controls both safety guardrails AND authorized packages, follows documented convention with guardrails/system-prompt.md and packages//approved.txt"]

• #PENDING [STORY] Story 2: Guardrails repo with package authorization

Feature 3: Audit Trail (feat:audit)

[Conversation Reference: "Use existing AuditLogService.log(), action_type=open_delegation_executed, log prompt truncated to 500 chars, engine, mode, repositories, job_id, guardrails_enabled"]

• #PENDING [STORY] Story 4: Delegation audit trail enhancement

Feature 5: Claude Server Proxy Tools (feat:cs-proxy)

[Conversation Reference: "I would like to add capabilities to proxy into claude server from neo. Register a repo, list repos, check health."]

• [STORY] Claude Server proxy tools (register repo, list repos, health check) #460 [STORY] Claude Server proxy tools (register repo, list repos, health check)

Feature 4: Web UI Configuration (feat:config-ui)

[Conversation Reference: "delegation_guardrails_repo dropdown from golden repos with filter/search, delegation_guardrails_enabled toggle, delegation_default_engine dropdown, delegation_default_mode dropdown"]

• #PENDING [STORY] Story 3: Web UI configuration for open delegation

Implementation Order: Story 1 --> Story 2 --> Story 4 --> Story 3 --> Story 5

Technical Implementation Standards

Permission Model

• New delegate_open permission string added to POWER_USER base permissions in user_manager.py
• ADMIN inherits from POWER_USER, so gets the permission automatically
• Normal users do NOT have this permission

Backward Compatibility

• Existing execute_delegation_function tool remains completely unchanged
• Existing create_job() method on ClaudeServerClient remains unchanged
• New create_job_with_options() is a separate method
• Existing poll_delegation_job tool reused without modification
• Existing callback mechanism reused without modification

Key Files to Modify

• user_manager.py -- add delegate_open permission to POWER_USER
• delegation_config.py -- add config fields + DEFAULT_GUARDRAILS_TEMPLATE constant
• claude_server_client.py -- new create_job_with_options(), add repo status polling
• handlers.py -- new handler after line 13308
• config_service.py -- expose new config fields
• config_section.html -- new Web UI fields (dropdown with filtering)
• New: tool_docs/admin/execute_open_delegation.md
• New: docs/guardrails-repo-convention.md

Engine and Mode Support

• Engines: claude-code, codex, gemini, opencode, q
• Modes: single (POST /jobs), collaborative (POST /jobs/orchestrated -- not yet supported), competitive (POST /jobs/competitive -- not yet supported)
• Unsupported modes return clear error, no fallback, no dead code

Risk Assessment and Mitigation

Technical Risks

Risk: Claude Server collaborative/competitive endpoints do not exist yet
Mitigation: Return clear error "Mode not yet supported by Claude Server" for these modes; no fallback logic, no dead code stubs

Risk: Repo registration on Claude Server is async and may timeout
Mitigation: Poll GET /repositories/{name} until cloneStatus="completed" using existing golden repo registration timeout from server config; surface timeout as clear error to user

Risk: Guardrails repo may not follow the expected convention (missing files, wrong structure)
Mitigation: If system-prompt.md not found in configured repo, fall back to DEFAULT_GUARDRAILS_TEMPLATE; log warning

Operational Risks

Risk: Prompt injection could attempt to override guardrails
Mitigation: Guardrails prepended as system-level instructions before user prompt; guardrails repo included in job repositories so agent can verify packages via CIDX MCP

Risk: Admin accidentally disables guardrails
Mitigation: guardrails_enabled defaults to true; Web UI shows clear indication of guardrails state

Dependencies and Prerequisites

Technical Dependencies

• Claude Server API (POST /jobs, GET /repositories/{name}, POST /repositories/register, POST /jobs/{id}/callbacks, POST /jobs/{id}/start)
• Existing golden repo infrastructure for guardrails repo storage and path resolution
• Existing AuditLogService for audit logging
• Existing poll_delegation_job MCP tool for result retrieval

Implementation Dependencies

• Story 1 (core delegation) must complete before Story 2 (guardrails integration into the handler)
• Story 2 (guardrails) must complete before Story 4 (audit -- needs guardrails_enabled in audit payload)
• Stories 1, 2, 4 must complete before Story 3 (Web UI -- needs all config fields defined)

Success Metrics and Validation

Functional Metrics

• Open delegation tool accessible and functional for poweruser and admin roles
• Guardrails correctly prepended to prompts from configured golden repo
• Audit entries queryable via existing audit log API with action_type filter

Quality Metrics

• Test coverage >90% for new code
• Zero regressions in existing delegation functionality
• Zero regressions in existing permission model
• All existing tests continue passing (fast-automation.sh)

Epic Completion Criteria

Definition of Done

• All 4 stories implemented and validated
• Complete test suite with >90% coverage for new code
• Guardrails repo convention documented in docs/guardrails-repo-convention.md
• Tool documentation created in tool_docs/admin/execute_open_delegation.md
• fast-automation.sh passes with zero failures
• Existing execute_delegation_function verified unchanged and functional
• Existing poll_delegation_job verified unchanged and functional

Acceptance Validation

• Power user can submit free-form objective and receive job_id
• Normal user gets access denied
• Guardrails from golden repo correctly prepended to prompt
• Default guardrails applied when no repo configured
• Audit trail captures all open delegation calls with full context
• Web UI config fields functional and persisted
• Collaborative/competitive modes return clear unsupported error

---

Epic Owner: Development team
Stakeholders: CIDX server users, system administrators
Success Measurement: Users can delegate any coding objective through CIDX MCP with safety guardrails and full audit trail

[jsbattig]

Story #456 (Open-ended delegation with engine and mode selection) completed

[jsbattig]

Story #457 (Guardrails repo with package authorization) completed

[jsbattig]

Story #458 (Delegation audit trail enhancement) completed

[jsbattig]

Story #459 (Web UI configuration for open delegation) completed