[Interop] Capability handshake contract for Aegis and Claude Code

[OneStepAt4time]

Problem

Aegis lacks a formal capability handshake for Claude Code integration. Feature behavior is inferred implicitly instead of negotiated explicitly.

Verified Status

TRACKED — needs implementation

Environment

• Aegis version: v2.5.3
• Branch: main
• Install method: npm/global

Root Cause in Code

app.post('/v1/hooks/:eventName', async (req, reply) => {
  if (!KNOWN_HOOK_EVENTS.has(eventName)) {
    return reply.status(400).send({ error: `Unknown hook event: ${eventName}` })
  }
  // process event directly
})

Hook processing validates events but does not negotiate a protocol version/capability set with the client before enabling behavior branches.

Impact

• Version drift can cause brittle integrations
• Harder backward compatibility management
• Feature rollout risk when clients differ in supported events/options

Proposed Fix

1. Define handshake schema with protocolVersion and capabilities.
2. Add feature gates driven by negotiated capabilities.
3. Emit compatibility diagnostics for unknown/out-of-policy clients.
4. Keep graceful downgrade path.

Test Plan

1. Client with partial capabilities -> feature downgrade works.
2. Unknown protocol version -> warning + safe fallback.
3. Full-capability client -> all gated features enabled.

Acceptance Criteria

• Handshake is mandatory for advanced integration paths.
• Capability gating prevents unsupported behavior.
• Diagnostics show negotiated capabilities per session.

Analysis Files

• docs/plans/aegis-claude-code-collaboration-analysis.md
• docs/plans/aegis-claude-code-technical-backlog.md
• docs/plans/github-open-issues-coverage-audit.md

[OneStepAt4time]

PM delegation update (Wave 2): assigned stream S8 on branch feat/885-capability-handshake. Scope: protocol/capability negotiation schema + feature gating + backward-compatible downgrade behavior. Gating: recommended after diagnostics baseline (#881). Definition of Done: negotiation tests passing, compatibility behavior verified, tsc/build/test green.

[OneStepAt4time]

Status update (2026-04-02 12:10): Stream planned in Wave 2. Branch: feat/885-capability-handshake. Current phase: schema and negotiation flow drafted. Next checkpoint: implementation starts after diagnostics baseline from #881.