feat(session-start): enrich session context with user/org info from API

[Umaaz]

Overview

This merge request significantly enhances the session start process by enriching the session context with user, organization, and integration details from the OpenTrace API. By fetching this information from the /info endpoint using the user's stored OAuth token, Claude gains crucial awareness of available source code providers (e.g., GitHub, GitLab) and organizational integrations. This allows for more relevant, context-aware interactions from the beginning of a session.

Technical Details

Files Changed:

• .claude-plugin/plugin.json

Summary of Changes:

• Plugin Version: The plugin version is updated from 0.0.4 to 0.0.5.
• API Integration: The session-start script now authenticates to the OpenTrace GET /info endpoint using the MCP OAuth token stored locally in ~/.claude/.credentials.json.
• Context Enrichment: The API response, parsed with jq, is used to append available source code connections and organization integrations to additionalContext, making them available to the model.
• Dynamic System Message: A system message is generated at startup to display the user and organization identity (e.g., user.name, organization.name), providing immediate feedback on the active context.
• Dependency Management: The script now proactively checks for curl and jq. If a dependency is missing, it gracefully degrades and displays a user-friendly message with installation instructions, clarifying the impact of the missing dependency.

Review Summary

• Key Findings & Actions Taken:
  1. Missing jq Dependency: It was noted that the fallback additionalContext for when jq is missing was too brief and lacked detailed instructions for the model on how to use OpenTrace tools.
     • Action: The full base_context content was restored to the fallback to ensure the model has the same level of guidance even when jq is not available.
  2. Missing curl Dependency: A suggestion was made to improve the warning message by explaining why the missing curl dependency is a problem.
     • Action: The message was updated to explicitly state that the absence of curl prevents the display of dynamic user and integration information, thereby managing user expectations.
• Approval Status: Approved. All suggestions have been incorporated.

Impact Assessment

• Security: This change introduces an API call using an existing OAuth token from a local credentials file. No sensitive credentials are hardcoded or exposed, adhering to security best practices.
• Performance: A single API call is added at session start, which may introduce a minor initialization delay. This is a necessary trade-off for the significant benefit of a richer, more accurate initial context.
• Maintainability: The addition of explicit dependency checks and clearer error messaging improves the plugin's robustness and makes it easier for users to self-diagnose and resolve setup issues.

---

Attached by run j-0da6be7c-7c1b-4897-bb95-1354a48a11a1

[opentrace]

Approved

[opentrace]

Review completed via automated analysis.

[opentrace]

The merge request introduces a valuable feature that enriches the session context with user, organization, and integration details from the API. The implementation is robust, including graceful degradation for missing dependencies like jq and curl. This enhancement will improve the AI's awareness of available tools and data sources, leading to a better user experience.

---

Attached by run j-43e4fd28-ab1d-4f61-b65b-9ee1892111fc

[opentrace]

Approved

[opentrace]

I've reviewed the changes. The version bump in the plugin.json is appropriate. The updates to the session-start script are a great improvement, adding dependency checks and dynamically fetching user information. I've made a couple of suggestions to improve the user experience when dependencies are missing, ensuring the model and user have the best possible context in all scenarios.

---

Attached by run j-0da6be7c-7c1b-4897-bb95-1354a48a11a1

[opentrace]

SUGGESTION: The fallback additionalContext for when jq is missing has been shortened and is now missing the detailed instructions on how to proactively use the OpenTrace tools (e.g., when to query, what follow-up tools to use). This detailed guidance is crucial for the model to use the tools effectively. Consider using the full base_context content here to ensure the model has the same level of instruction even when jq is not available.

Suggested change

"additionalContext": "You have access to OpenTrace, a knowledge graph that maps the user's system architecture, service relationships, and project metadata. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when you need context beyond the local project — such as discovering upstream/downstream services, finding related classes or endpoints in other repositories, understanding deployment topology, looking up issues and tickets, or tracing how components connect across the system. When a question touches anything outside the current repo, consider checking OpenTrace. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for.\n\nProactively query OpenTrace (search_nodes, get_neighbors, traverse_dependencies) before starting work when the user's message:\n- References named services, APIs, or external integrations\n- Mentions system components, pipelines, or infrastructure\n- Involves incidents, outages, production issues, or on-call concerns\n- Asks about dependencies, impact, blast radius, or upstream/downstream effects\n- Involves editing code that integrates with external services or shared middleware\n\nAfter receiving OpenTrace tool results, automatically call the most useful follow-up tool to deepen the exploration rather than stopping to ask the user what to do next. Choose the follow-up based on which tool just ran:\n- search_nodes or query_nodes → call get_neighbors on the most relevant node\n- get_node → call get_neighbors or traverse_incoming/traverse_outgoing to understand the node's role\n- get_neighbors → call traverse_dependencies to go deeper, or find_path between two interesting neighbors\n- traverse_dependencies, traverse_incoming, or traverse_outgoing → call get_node for details on the most relevant result, or find_path between notable endpoints\n- find_path → call get_node to inspect the most critical intermediate node\n- get_node_statistics → call search_nodes to explore the most connected node types\n- find_similar_nodes → call get_neighbors to compare connection patterns\n- load_source or load_source_from_node → no follow-up needed\nDo not re-call the tool that just ran. Pick the single best follow-up. If the user's question has already been fully answered, stop and present the answer instead of exploring further."

"additionalContext": "You have access to OpenTrace, a knowledge graph that maps the user's system architecture, service relationships, and project metadata. Use your local tools (Read, Grep, Glob, etc.) for anything within the current codebase. Use OpenTrace when you need context beyond the local project — such as discovering upstream/downstream services, finding related classes or endpoints in other repositories, understanding deployment topology, looking up issues and tickets, or tracing how components connect across the system. When a question touches anything outside the current repo, consider checking OpenTrace. Always inform the user when you are about to use OpenTrace and briefly explain what you are looking for.\n\nProactively query OpenTrace (search_nodes, get_neighbors, traverse_dependencies) before starting work when the user's message:\n- References named services, APIs, or external integrations\n- Mentions system components, pipelines, or infrastructure\n- Involves incidents, outages, production issues, or on-call concerns\n- Asks about dependencies, impact, blast radius, or upstream/downstream effects\n- Involves editing code that integrates with external services or shared middleware\n\nAfter receiving OpenTrace tool results, automatically call the most useful follow-up tool to deepen the exploration rather than stopping to ask the user what to do next. Choose the follow-up based on which tool just ran:\n- search_nodes or query_nodes → call get_neighbors on the most relevant node\n- get_node → call get_neighbors or traverse_incoming/traverse_outgoing to understand the node's role\n- get_neighbors → call traverse_dependencies to go deeper, or find_path between two interesting neighbors\n- traverse_dependencies, traverse_incoming, or traverse_outgoing → call get_node for details on the most relevant result, or find_path between notable endpoints\n- find_path → call get_node to inspect the most critical intermediate node\n- get_node_statistics → call search_nodes to explore the most connected node types\n- find_similar_nodes → call get_neighbors to compare connection patterns\n- load_source or load_source_from_node → no follow-up needed\nDo not re-call the tool that just ran. Pick the single best follow-up. If the user's question has already been fully answered, stop and present the answer instead of exploring further."

[opentrace]

SUGGESTION: A previous suggestion (in a now-resolved discussion) recommended explaining why the missing curl dependency is a problem. This change is missing that context. It would be more helpful for the user to know that dynamic information cannot be fetched without curl.

Suggested change

	system_msg=$'\n\n\tOpenTrace is active — system architecture insights are available.\n\n\t⚠ Missing dependency: curl. Install with: brew install curl (macOS) or sudo apt install curl (Linux).'
	system_msg=$'\n\n\tOpenTrace is active — system architecture insights are available.\n\n\t⚠ Missing dependency: curl. Install with: brew install curl (macOS) or sudo apt install curl (Linux).\n\tDynamic user and integration info cannot be displayed.'

[opentrace]

The merge request is well-documented and introduces a valuable feature enhancement. The changes improve the user experience by providing better context at the start of a session. The implementation is robust, including necessary dependency checks and improved error messaging. Security implications have been considered, and the performance impact is acceptable. The review summary indicates that feedback has already been incorporated. This is a high-quality change.

---

Attached by run j-0da6be7c-7c1b-4897-bb95-1354a48a11a1