Feature Request: Evolve `additionalContext` into a Structured, Interactive, and Declarative Agentic Framework

Title: Feature Request: Evolve additionalContext into a Structured, Interactive, and Declarative Agentic Framework

Labels: feature-request, enhancement, hooks, agentic-loop, developer-experience, sdk

Is your feature request related to a problem? Please describe.

The newly introduced additionalContext feature for hooks is a strategic leap forward, successfully laying the groundwork for transforming Claude Code into a proactive, context-aware development partner. However, analysis of the current implementation and feedback from multiple developers reveals several key limitations that prevent it from reaching its full potential:

1. Unstructured String Limitation: The current implementation accepts only a single, unstructured string. This forces hook developers to manually serialize rich data (Git status, test results, ticket details) into a flat text block. The model must then expend reasoning capacity to parse this string, an inefficient and error-prone process that becomes brittle when multiple hooks contribute context.

1. Asynchronous Feedback Loop: The feedback loop is asynchronous. A PostToolUse hook can inject context (e.g., linter errors), but this is primarily for the next agentic turn. The agent often completes its current task and responds to the user before it has a chance to process the new feedback, creating a disjointed experience and breaking the autonomous flow.

1. High Barrier to Entry: The current hook system requires developers to write, manage, and configure shell scripts even for common, high-value use cases like injecting the current Git branch. This friction creates a high barrier to entry that may limit adoption of this powerful feature.

1. Lack of Interactivity and Transparency: The context injection is entirely "silent," which is not always ideal. Critical decision points, such as using a deprecated API or writing potentially insecure code, would be better handled through interactive guidance. Furthermore, the silent nature makes it difficult for users to know what context the agent is receiving, hindering trust and debuggability.

To fully realize the vision of a "proactive AI teammate," additionalContext must evolve from a simple information injector into a more robust, structured, and interactive framework.

Describe the solution you'd like

We propose a multi-faceted enhancement to the hooks system that addresses these limitations by introducing structured data, tighter agentic control, and a simplified developer experience.

Part 1: Introduce Structured & Typed Context Blocks

Evolve the additionalContext field from a string to an Array<ContextBlock> for richer, more reliable context. This allows multiple hooks to contribute context without conflict and eliminates parsing ambiguity for the model.

Proposed ContextBlock Schema:

{
  "source": "string",            // For debuggability, e.g., "git-status-hook.sh"
  "label": "string",             // A human-readable title for UI display, e.g., "Git Status"
  "type": "string",              // Semantic type for the model, e.g., "git_status", "test_failure"
  "priority": "low" | "normal" | "high", // A hint for the model's attention
  "content": "string | object",  // The payload, allowing for structured JSON
  "display": "model" | "user" | "both" // Controls visibility (model-only, user-only, or both)
}

This structured approach would enable a PostToolUse hook to return a clear, unambiguous test failure report that the model can act on reliably, and a SessionStart hook to provide multiple, distinct pieces of context (Git, CI, Tickets) simultaneously. The display flag would also allow for "briefing" the user on the context being provided to the model, increasing transparency.

Part 2: Enhance Hook Output for Agentic Control

Introduce new top-level fields in the hook's JSON output to give developers control over the agentic loop itself.

1. Immediate Self-Correction (decision: "continue_with_feedback"):

For PostToolUse hooks, allow a hook to instruct the agent to immediately continue processing based on new feedback without ending the current turn. When a hook returns this decision, the additionalContext is injected, and the agent is immediately re-prompted to continue its task, creating a true, atomic self-correction cycle.

1. Interactive User Prompts (userInteraction):

Allow hooks to pause the agentic loop and present a prompt with predefined choices to the user. This is ideal for guardrails and critical decision points.

Proposed userInteraction Schema:
``json
{
"userInteraction": {
"prompt": "⚠️ **Deprecation Warning:** You mentioned OldComponent, which is deprecated. We recommend migrating to NewComponent.",
"choices": [
{
"label": "Migrate to NewComponent",
"action": "PREPEND_CONTEXT",
"context": "User has chosen to migrate. Please refactor the request to use NewComponent."
},
{ "label": "Proceed Anyway", "action": "CONTINUE" },
{ "label": "Abort", "action": "ABORT" }
]
}
}
``

Part 3: Simplify Configuration with Declarative Providers

Lower the barrier to entry by introducing a "no-code" way to configure common context providers directly in settings.json, coexisting with the powerful script-based system.

Proposed Declarative settings.json:

// .claude/settings.json
{
  "additionalContext": {
    "onSessionStart": [
      "gitBranch",
      "gitUncommittedChanges"
    ],
    "onUserPromptSubmit": [
      {
        "provider": "ticketInfo",
        "pattern": "(ENG|PROJ)-\\d+",
        "source": "jira" 
      }
    ]
  },
  // ... existing hooks config for custom scripts
}

This would be complemented by a /context management command to provide a wizard-like UI for discovering, adding, and managing these providers, abstracting away the complexity of manual JSON editing.

A "Golden Path" Workflow with the Proposed Solution

This new framework enables a significantly more intelligent and robust workflow.

1. Session Start: A user starts claude. A declarative provider in settings.json runs git status. The hook returns a structured context block with display: "both".

• User sees: A formatted block saying "Briefing Claude: On branch feature/login, 3 files modified."
• Claude gets: {"type": "git_status", "content": {...}}

1. User Prompt: The user asks, "Fix the login flow using useLegacyAuth()."

• A UserPromptSubmit hook detects the deprecated function and returns an interactive prompt.
• User sees: "Warning: useLegacyAuth is deprecated. [Use useNewAuth()] or [Proceed Anyway]?" The user selects the modern option.
• Claude gets: The original prompt, prepended with "User chose to migrate. Refactor the request to use useNewAuth()."

1. Code Generation & Self-Correction:

• Claude: (Tool Use) Edit auth.js with the new logic.
• A PostToolUse hook runs the unit tests. A test fails.
• The hook returns:

``json
{
"decision": "continue_with_feedback",
"hookSpecificOutput": {
"additionalContext": [{
"label": "Unit Test Failure",
"type": "test_failure",
"priority": "high",
"content": { "file": "auth.test.js", "error": "Expected 2 arguments, received 1" },
"display": "model"
}]
}
}
``

• Claude: (Agent loop continues immediately) "My last edit broke a unit test. The error indicates a missing argument. I will now fix auth.test.js."
• Claude: (Tool Use) Edit auth.test.js.
• The PostToolUse hook runs again. Tests pass. The hook returns a standard success response.

1. Final Response:

• Claude: "I have refactored the login flow to use the modern useNewAuth() function and fixed the corresponding unit tests. All tests are now passing."

Describe alternatives you've considered

The alternative is the current implementation: an asynchronous, string-based system. While functional, it is less reliable, less efficient, and provides a poorer developer experience. It requires complex prompt engineering within hook scripts and cannot support the robust, interactive, and autonomous workflows described above.

Additional context

This proposal represents a holistic evolution of the additionalContext feature, transforming it from a simple data pipe into a comprehensive framework for agentic control. By implementing structured data, interactive loops, and a simplified configuration experience, Claude Code would more fully deliver on its strategic vision of becoming an indispensable, proactive AI development partner.