Skip to content

docs(coding-agents): Augment Code application session tracing (TH-8291) - #920

Merged
nik13 merged 11 commits into
mainfrom
feat/th-8291-augment-code
Nov 6, 2026
Merged

nik13 merged 11 commits into
mainfrom
feat/th-8291-augment-code

Conversation

@nik13

@nik13 nik13 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

TH-8291: document Auggie CLI 0.36.0 session tracing on macOS through the shared hook-to-OTLP emitter.

  • Merge main and register Augment Code in the shared integration catalog.
  • Align the guide and installed configuration on SessionStart, Stop, and SessionEnd; explain project-scoped installation, privacy, credentials, and removal.
  • Remove verification diaries and competitor comparisons from the customer guide.
  • Add page/configuration parity tests and GitHub-hosted adapter, installer, and silent-wrapper checks on Linux and macOS.
  • Include main’s browser-runner compatibility fix and pin the Python 3.9 contract job to Ubuntu 24.04.

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

…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
nik13 force-pushed the feat/th-8291-augment-code branch from 5729080 to cb53342 Compare October 15, 2026 02:50
nik13 and others added 4 commits October 15, 2026 08:37
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… 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
nik13 marked this pull request as ready for review October 21, 2026 22:59
Base automatically changed from feat/th-8229-cursor-hook-to-otlp to main October 29, 2026 05:37
nik13 and others added 6 commits November 5, 2026 16:32
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>
@nik13
nik13 merged commit 742b904 into main Nov 6, 2026
10 checks passed
@nik13
nik13 deleted the feat/th-8291-augment-code branch November 6, 2026 07:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant