Repository navigation
docs(coding-agents): Augment Code application session tracing (TH-8291) - #920
Merged
Merged
Conversation
…acing (TH-8291) Auggie CLI hook recipe on the shared hook-to-OTLP emitter: - adapters/augment.py maps the documented hooks (https://docs.augmentcode.com/cli/hooks): SessionStart/SessionEnd -> session keyed by conversation_id, PostToolUse -> tool span (ERROR on tool_error), Stop -> "Agent stop" span with agent_stop_cause (ERROR on "error"). Auggie sends no turn id, tool call id or timing, so there are no turn spans and PreToolUse is not mapped. workspace_roots, the includeUserContext/includeConversationData/includeMCPMetadata blocks and file_changes contents are never exported, even with content capture on. - Contract tests on doc-shaped payloads that turn every opt-in metadata block on. - examples/coding-agents/augment-code: settings.json hooks (no metadata flags), futureagi-hook.sh wrapper (Auggie only runs .sh hook scripts; stdout discarded because SessionStart output is added to the agent context), install.sh, run_e2e.sh. - Page integrations/coding-agents/augment-code and its nav entry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13
force-pushed
the
feat/th-8291-augment-code
branch
from
October 15, 2026 02:50
5729080 to
cb53342
Compare
… truth (TH-8291)
Hooks never block or steer Auggie:
- Auggie runs the documented .sh hook path directly (shell: false), so the
guard lives in futureagi-hook.sh: (python3 -B emit.py augment 2>/dev/null
|| true) >/dev/null; exit 0, with no external commands (works with an
empty PATH). No output, so SessionStart adds nothing to the agent context
and Stop can never answer {"decision": "block"}.
- New test_augment_hooks_config runs every installed command the way Auggie
0.36.0 resolves it (port of the bundle's dao/QIt) and via sh -c with the
payload on stdin and as a trailing heredoc (sh/bash/zsh/dash), for a plain
home, one with a space and one with & # " \ $HOME and backticks: exit 0,
no stdout/stderr, payload received verbatim, no __pycache__; emitter or
python3 missing: exit 0, no output.
- install.sh builds settings with json.dump (the sed replacement broke on
& # " \), single-quotes a path Auggie would otherwise split or hand to
bash, and gains --project REPO (REPO/.augment/settings.local.json, CLI
only) so the user file the IDE extensions also read can stay untouched.
Privacy:
- Fixture: realistic MCP metadata (server name is part of the tool name by
design), user_prompt and _exchange canaries (0.36.0 can put both in the
hook input), tool error text with a home path and user name. Tests assert
the canaries never leave, the error text is absent by default and
/Users/<user>/... with capture on; every 0.36.0 stop cause incl.
empty_completion; dead capture-mode skip removed.
Page: PreToolUse is skipped because it can block (not "unpairable"), MCP
server names, user_prompt/_exchange, paths inside opted-in content,
empty_completion, Windows unsupported, --log-file - (hidden flags; default
log in $TMPDIR), repo-only install and IDE note, resumed-conversation
caveat, Uninstall, Next Steps heading. Adapter docstring matches the core
(root span is sent with the first child).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and {} entry (TH-8291)
- install.sh --project: the workspace file holds the absolute wrapper path
(the home directory), so add it to the repository's .git/info/exclude
unless git already ignores it. No tracked file is changed; works from a
subfolder and in a linked worktree; outside git it prints a reminder.
- install.sh: build the hooks JSON before copying, so a home path with a
single quote stops with no partial install.
- Page: drop the "agent context shows {}" troubleshooting entry (0.36.0
parses JSON stdout, {} included; only plain-text SessionStart output
reaches the agent context), document the git exclusion and the
single-quote limit.
- Guard rationale (page, wrapper comment, test docstring): the guard lives
in the script because Augment documents a script path, not because a
one-line guarded command could not run.
- Tests: exclude list (subfolder, root, re-run, worktree), existing ignore
rule left alone, single-quote home installs nothing, non-git reminder.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ification (TH-8291) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
nik13
marked this pull request as ready for review
October 21, 2026 22:59
Merge main and use the shared integration catalog instead of the obsolete sidebar. Limit the recipe and installed hooks to Auggie 0.36.0 lifecycle events, preserve privacy constraints, and keep historical verification notes outside the public guide. Add page contracts and GitHub-hosted adapter/installer checks without claiming live tool tracing. Co-Authored-By: Claude Code <noreply@anthropic.com>
Ubuntu latest now resolves to 26.04, which lacks the Python 3.9 setup binary and Playwright 1.56.1 Chromium dependencies. Run these two jobs on 24.04 while retaining the macOS hook contract job. Co-Authored-By: Claude Code <noreply@anthropic.com>
Keep main's equivalent Ubuntu 24.04 browser-runner pin and resolve the comment-only merge conflict so the session guide remains mergeable. Co-Authored-By: Claude Code <noreply@anthropic.com>
Match Auggie 0.36.0's command parsing instead of quoting every path outside an ASCII allowlist. Unicode and parentheses-only home paths are spawned literally, so surrounding quotes otherwise make all session hooks fail to launch. Exercise both paths through the installer and all session hooks in the existing GitHub-hosted Linux/macOS contract suite. Assert the exact resolved executable and isolate each home case's session state while retaining space and shell-metacharacter coverage. Co-Authored-By: Claude Code <noreply@anthropic.com>
The macOS contract job caught Bash 3.2 interpreting a literal backtick inside the command-substitution heredoc. Use the equivalent regex escape without changing Auggie's dispatch-character matching. Co-Authored-By: Claude Code <noreply@anthropic.com>
The macOS contract still rejects quotes inside the command-substitution heredoc. Put the quoted Python heredoc in a shell function and capture that function's output instead, avoiding Bash 3.2's nested-heredoc parsing while preserving failure-before-copy behavior. Co-Authored-By: Claude Code <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
TH-8291: document Auggie CLI 0.36.0 session tracing on macOS through the shared hook-to-OTLP emitter.
Scope
New macOS CLI conversations produce an Auggie session with Agent stop children. Tool tracing, resumed conversations, IDE extensions, and other operating systems are outside this recipe. Existing synthetic tool-parser regression coverage is retained without claiming live tool support.
The shared emitter is already on main; no new package or account is required to complete this documentation change.
🤖 Generated with Claude Code