From cb53342aee2eaeb8149a1adf4d8facb67aa928ca Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Wed, 14 Oct 2026 18:24:34 -0700 Subject: [PATCH 1/8] docs(coding-agents): Augment Code (Auggie CLI) application session tracing (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 --- .../augment-code/futureagi-hook.sh | 10 ++ .../coding-agents/augment-code/install.sh | 36 +++++ .../coding-agents/augment-code/run_e2e.sh | 39 ++++++ .../coding-agents/augment-code/settings.json | 49 +++++++ .../hook-to-otlp/adapters/augment.py | 98 ++++++++++++++ .../tests/fixtures/augment/session.jsonl | 10 ++ .../tests/test_augment_adapter.py | 98 ++++++++++++++ src/lib/navigation.ts | 1 + .../coding-agents/augment-code.mdx | 127 ++++++++++++++++++ 9 files changed, 468 insertions(+) create mode 100755 examples/coding-agents/augment-code/futureagi-hook.sh create mode 100755 examples/coding-agents/augment-code/install.sh create mode 100755 examples/coding-agents/augment-code/run_e2e.sh create mode 100644 examples/coding-agents/augment-code/settings.json create mode 100644 examples/coding-agents/hook-to-otlp/adapters/augment.py create mode 100644 examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl create mode 100644 examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py create mode 100644 src/pages/docs/integrations/coding-agents/augment-code.mdx diff --git a/examples/coding-agents/augment-code/futureagi-hook.sh b/examples/coding-agents/augment-code/futureagi-hook.sh new file mode 100755 index 000000000..3e6fe9265 --- /dev/null +++ b/examples/coding-agents/augment-code/futureagi-hook.sh @@ -0,0 +1,10 @@ +#!/bin/sh +# Auggie hook command for Future AGI. Auggie only runs hook scripts with a +# .sh extension, so this wrapper starts the Python emitter. stdout goes to +# /dev/null: Auggie adds SessionStart stdout to the agent's context, and +# this hook has nothing to tell the agent. It always exits 0. +HERE="$(cd "$(dirname "$0")" && pwd)" +EMIT="$HERE/emit.py" +[ -f "$EMIT" ] || EMIT="$HERE/../hook-to-otlp/emit.py" +python3 "$EMIT" augment >/dev/null 2>&1 +exit 0 diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh new file mode 100755 index 000000000..c0c706cb5 --- /dev/null +++ b/examples/coding-agents/augment-code/install.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +# Install the Future AGI hook emitter for Augment's Auggie CLI. +# +# ./install.sh +# +# Copies emit.py, the Augment adapter and the futureagi-hook.sh wrapper into +# ~/.augment/fi-hook-to-otlp/ and writes ~/.augment/settings.json if there is +# none. An existing settings.json is never modified: the script prints the +# "hooks" entries to merge instead. No metadata flags are set, so Auggie does +# not add user context or conversation data to the hook input. +set -euo pipefail + +HERE="$(cd "$(dirname "$0")" && pwd)" +EMITTER="$HERE/../hook-to-otlp" +AUGMENT_DIR="$HOME/.augment" +DEST="$AUGMENT_DIR/fi-hook-to-otlp" + +mkdir -p "$DEST/adapters" +cp "$EMITTER/emit.py" "$DEST/emit.py" +cp "$EMITTER/adapters/__init__.py" "$EMITTER/adapters/base.py" "$EMITTER/adapters/augment.py" "$DEST/adapters/" +cp "$HERE/futureagi-hook.sh" "$DEST/futureagi-hook.sh" +chmod +x "$DEST/futureagi-hook.sh" +echo "emitter: $DEST" + +SETTINGS="$(sed "s#/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh#$DEST/futureagi-hook.sh#g" "$HERE/settings.json")" +if [[ -e "$AUGMENT_DIR/settings.json" ]]; then + echo "kept existing $AUGMENT_DIR/settings.json; merge these entries into its \"hooks\" object:" + echo "$SETTINGS" +else + echo "$SETTINGS" > "$AUGMENT_DIR/settings.json" + echo "hooks: $AUGMENT_DIR/settings.json" +fi + +echo +echo "Credentials: put FI_API_KEY, FI_SECRET_KEY and FI_PROJECT_NAME in" +echo "~/.config/fi-hook-to-otlp/env (chmod 600), or export them before starting auggie." diff --git a/examples/coding-agents/augment-code/run_e2e.sh b/examples/coding-agents/augment-code/run_e2e.sh new file mode 100755 index 000000000..bac4bb3df --- /dev/null +++ b/examples/coding-agents/augment-code/run_e2e.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Drive the real emitter, through the same futureagi-hook.sh wrapper Auggie +# runs, with Auggie hook payloads into a Future AGI collector. +# +# FI_API_KEY=... FI_SECRET_KEY=... FI_BASE_URL=http://localhost:14338 \ +# FI_PROJECT_NAME=augment-e2e ./run_e2e.sh [fixture.jsonl] +# +# Default input is the documented-shape session in +# ../hook-to-otlp/tests/fixtures/augment/session.jsonl (it also turns on every +# opt-in metadata block, to show they are dropped). Each line runs the wrapper +# as its own process, exactly as Auggie runs a hook command. Every run gets a +# fresh conversation id, printed at the end with its trace id. +set -euo pipefail + +HERE="$(cd "$(dirname "$0")" && pwd)" +EMITTER="$HERE/../hook-to-otlp" +FIXTURE="${1:-$EMITTER/tests/fixtures/augment/session.jsonl}" +: "${FI_API_KEY:?set FI_API_KEY}" "${FI_SECRET_KEY:?set FI_SECRET_KEY}" +export FI_PROJECT_NAME="${FI_PROJECT_NAME:-augment-e2e}" + +RUN_ID="augment-e2e-$(date +%Y%m%d%H%M%S)-$$" +python3 - "$FIXTURE" "$RUN_ID" <<'PY' | while IFS= read -r payload; do +import json, sys +for line in open(sys.argv[1], encoding="utf-8"): + if line.strip(): + payload = json.loads(line)["payload"] + payload["conversation_id"] = sys.argv[2] + print(json.dumps(payload)) +PY + rc=0 + printf '%s' "$payload" | "$HERE/futureagi-hook.sh" || rc=$? + event="$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin)["hook_event_name"])')" + echo "$event exit=$rc" + sleep "${REPLAY_SLEEP:-0.3}" +done + +TRACE_ID="$(cd "$EMITTER" && python3 -c 'import sys, emit; print(emit.trace_id("augment", sys.argv[1]))' "$RUN_ID")" +echo "conversation_id=$RUN_ID" +echo "trace_id=$TRACE_ID" diff --git a/examples/coding-agents/augment-code/settings.json b/examples/coding-agents/augment-code/settings.json new file mode 100644 index 000000000..f70bdf7db --- /dev/null +++ b/examples/coding-agents/augment-code/settings.json @@ -0,0 +1,49 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": ".*", + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ], + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", + "timeout": 5000 + } + ] + } + ] + } +} diff --git a/examples/coding-agents/hook-to-otlp/adapters/augment.py b/examples/coding-agents/hook-to-otlp/adapters/augment.py new file mode 100644 index 000000000..232de01f1 --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/adapters/augment.py @@ -0,0 +1,98 @@ +"""Augment Code (Auggie CLI) hooks -> normalized span events. + +Payload shapes follow https://docs.augmentcode.com/cli/hooks (read +2026-10-14): every event carries ``hook_event_name``, ``conversation_id`` +(the session) and ``workspace_roots``. Tool events carry ``tool_name``, +``tool_input`` and ``is_mcp_tool``; ``PostToolUse`` adds ``tool_output``, +``tool_error`` and ``file_changes``. ``Stop`` carries ``agent_stop_cause``. +Auggie sends no turn id, no tool call id, no tool timing, no model id and +no token counts, so this adapter does not produce turn spans and tool spans +have no measured duration. + +Mapped events: + + SessionStart -> session start (root span exported, re-exported later) + PostToolUse -> tool span (ERROR when tool_error is set) + tool_input / tool_output / tool_error = content + Stop -> event span "Agent stop" (ERROR when the cause is + "error"); the last cause is also kept on the session + SessionEnd -> session end + +``PreToolUse`` is not mapped: without a tool call id it cannot be paired +with ``PostToolUse``, and it is the one hook that can block a tool. + +Never exported, even with content capture on: ``workspace_roots``, the +``context`` object (``includeUserContext``: user email, model display name), +the ``conversation`` object (``includeConversationData``), ``mcp_metadata``, +and file contents from ``file_changes`` (only the count and change types). +""" +from __future__ import annotations + +from typing import Any, Dict, List + +from adapters.base import ( + END, ERROR, EVENT, INSTANT, OK, SESSION, START, TOOL, UPDATE, + SpanEvent, compact, first, +) + +APP = "augment" +DISPLAY_NAME = "Auggie" +SERVICE_NAME = "auggie-cli" + + +def _file_change_attrs(payload: Dict[str, Any]) -> Dict[str, Any]: + changes = payload.get("file_changes") + if not isinstance(changes, list): + return {} + types = sorted({str(c.get("changeType")) for c in changes if isinstance(c, dict) and c.get("changeType")}) + return compact({ + "augment.tool.file_changes.count": len(changes), + "augment.tool.file_changes.types": types, + }) + + +def parse(event: str, payload: Dict[str, Any]) -> List[SpanEvent]: + session = first(payload, "conversation_id") + if not session: + return [] # R-01: never invent a session id + sid = str(session) + + if event == "SessionStart": + return [SpanEvent(START, SESSION, sid)] + + if event == "SessionEnd": + return [SpanEvent(END, SESSION, sid)] + + if event == "PostToolUse": + tool_name = str(first(payload, "tool_name") or "tool") + error = payload.get("tool_error") + failed = error not in (None, "") + return [SpanEvent( + END, TOOL, sid, + name=tool_name, + status=ERROR if failed else OK, + status_message="tool error" if failed else None, + input=payload.get("tool_input"), + output=None if failed else payload.get("tool_output"), + error_message=error if failed else None, + attributes=compact({ + "augment.tool.name": tool_name, + "augment.tool.is_mcp": payload.get("is_mcp_tool"), + **_file_change_attrs(payload), + }), + )] + + if event == "Stop": + cause = payload.get("agent_stop_cause") + failed = cause == "error" + return [ + SpanEvent( + INSTANT, EVENT, sid, name="Agent stop", + status=ERROR if failed else OK, + status_message="agent stopped with error" if failed else None, + attributes=compact({"augment.stop.cause": cause}), + ), + SpanEvent(UPDATE, SESSION, sid, attributes=compact({"augment.stop.last_cause": cause})), + ] + + return [] diff --git a/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl new file mode 100644 index 000000000..d358f901f --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl @@ -0,0 +1,10 @@ +{"event": "SessionStart", "payload": {"hook_event_name": "SessionStart", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} +{"event": "PreToolUse", "payload": {"hook_event_name": "PreToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "is_mcp_tool": false}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG README.md", "is_mcp_tool": false, "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "README.md"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG # demo", "is_mcp_tool": false}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "str-replace-editor", "tool_input": {"path": "src/auth.ts", "old_str_1": "TOOL_INPUT_MARKER_AUG old", "new_str_1": "TOOL_INPUT_MARKER_AUG new"}, "tool_output": "File edited successfully", "is_mcp_tool": false, "file_changes": [{"path": "src/auth.ts", "changeType": "edit", "content": "FILE_CONTENT_CANARY new", "oldContent": "FILE_CONTENT_CANARY old"}]}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "search_example-server", "tool_input": {"query": "TOOL_INPUT_MARKER_AUG docs"}, "tool_error": "ERROR_MARKER_AUG permission denied", "is_mcp_tool": true, "mcp_metadata": {"mcpDecision": "yes", "mcpExecutedToolServerName": "MCP_SERVER_CANARY"}}} +{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "end_turn", "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "conversation": {"userPrompt": "CONVERSATION_CANARY prompt", "agentTextResponse": "CONVERSATION_CANARY reply", "agentCodeResponse": [{"path": "src/auth.ts", "changeType": "edit", "content": "CONVERSATION_CANARY code"}]}}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "src/auth.ts"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG body", "is_mcp_tool": false}} +{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "error"}} +{"event": "SessionEnd", "payload": {"hook_event_name": "SessionEnd", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py new file mode 100644 index 000000000..0b12d5257 --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py @@ -0,0 +1,98 @@ +"""Auggie CLI adapter contract tests against payloads shaped as https://docs.augmentcode.com/cli/hooks documents them. + +The fixture turns on every opt-in metadata block Auggie offers +(``context``, ``conversation``, ``mcp_metadata``, ``file_changes``) to prove +the adapter drops them. +""" +from __future__ import annotations + +import json +import tempfile +import unittest + +from tests.helpers import FIXTURES, attrs, by_name, config, latest, load_jsonl, replay + +import emit +from adapters import augment +from adapters.base import SESSION, TURN + +SESSION_FIXTURE = FIXTURES / "augment" / "session.jsonl" +SID = "fixture-conv-aug-0001" +MARKERS = ("TOOL_INPUT_MARKER_AUG", "TOOL_OUTPUT_MARKER_AUG", "ERROR_MARKER_AUG") +# Never exported, even with content capture on (R-03, R-04, section 12). +NEVER = ("fixture.user@example.com", "MODEL_LABEL_CANARY", "CONVERSATION_CANARY", + "FILE_CONTENT_CANARY", "MCP_SERVER_CANARY", "/Users/fixture/project") + + +class AugmentAdapterTest(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.records = load_jsonl(SESSION_FIXTURE) + + def tearDown(self): + self.tmp.cleanup() + + def spans(self, capture=False): + extra = {"FI_HOOK_CAPTURE_CONTENT": "1"} if capture else {} + return replay(augment, config("augment", self.tmp.name, **extra), self.records) + + def test_one_trace_keyed_by_conversation_id(self): + spans = self.spans() + self.assertEqual({s["traceId"] for s in spans}, {emit.trace_id("augment", SID)}) + root_id = emit.span_id("augment", SID, SESSION, "") + root = latest(spans, root_id) + self.assertEqual(root["name"], "Auggie session") + self.assertEqual(attrs(root)["fi.span.kind"], "AGENT") + self.assertEqual(attrs(root)["augment.stop.last_cause"], "error") + children = sorted(s["name"] for s in spans if s.get("parentSpanId") == root_id) + self.assertEqual(children, ["Agent stop", "Agent stop", "launch-process", + "search_example-server", "str-replace-editor", "view", "view"]) + self.assertFalse([s for s in spans if attrs(s).get("coding_agent.scope") == TURN]) + + def test_tools_are_unique_spans_with_status(self): + spans = self.spans() + views = by_name(spans, "view") + self.assertEqual(len({s["spanId"] for s in views}), 2) + a = attrs(views[0]) + self.assertEqual((a["fi.span.kind"], a["gen_ai.tool.name"], a["augment.tool.is_mcp"]), + ("TOOL", "view", False)) + self.assertNotIn("gen_ai.tool.call.id", a) # Auggie sends no tool call id + mcp = by_name(spans, "search_example-server")[0] + self.assertEqual(mcp["status"], {"code": 2, "message": "tool error"}) + self.assertTrue(attrs(mcp)["augment.tool.is_mcp"]) + edit = attrs(by_name(spans, "str-replace-editor")[0]) + self.assertEqual(edit["augment.tool.file_changes.count"], "1") + self.assertEqual(edit["augment.tool.file_changes.types"], {"values": [{"stringValue": "edit"}]}) + + def test_stop_cause_and_error(self): + stops = by_name(self.spans(), "Agent stop") + self.assertEqual([attrs(s)["augment.stop.cause"] for s in stops], ["end_turn", "error"]) + self.assertEqual(stops[0]["status"]["code"], 1) + self.assertEqual(stops[1]["status"], {"code": 2, "message": "agent stopped with error"}) + + def test_pre_tool_use_is_not_mapped(self): + self.assertEqual(augment.parse("PreToolUse", self.records[1]["payload"]), []) + + def test_default_export_has_no_content_or_pii(self): + encoded = json.dumps(self.spans()) + for marker in MARKERS + NEVER: + self.assertNotIn(marker, encoded, marker) + + def test_capture_content_opt_in_still_drops_metadata_blocks(self): + spans = self.spans(capture=True) + encoded = json.dumps(spans) + for marker in MARKERS: + self.assertIn(marker, encoded, marker) + for marker in NEVER: + if marker == "/Users/fixture/project": + continue # not present in any content field of this fixture either + self.assertNotIn(marker, encoded, marker) + mcp = attrs(by_name(spans, "search_example-server")[0]) + self.assertIn("ERROR_MARKER_AUG", mcp["exception.message"]) + + def test_missing_conversation_id_is_dropped(self): + self.assertEqual(augment.parse("PostToolUse", {"tool_name": "view"}), []) + + +if __name__ == "__main__": + unittest.main() diff --git a/src/lib/navigation.ts b/src/lib/navigation.ts index 9ebda640c..ab68067af 100644 --- a/src/lib/navigation.ts +++ b/src/lib/navigation.ts @@ -958,6 +958,7 @@ export const tabNavigation: NavTab[] = [ items: [ { title: 'Hook-to-OTLP Emitter', href: '/docs/integrations/coding-agents/hook-to-otlp' }, // coding-agents:augment-code + { title: 'Augment Code (Auggie CLI)', href: '/docs/integrations/coding-agents/augment-code' }, // coding-agents:claude-code // coding-agents:claude-cowork // coding-agents:codex diff --git a/src/pages/docs/integrations/coding-agents/augment-code.mdx b/src/pages/docs/integrations/coding-agents/augment-code.mdx new file mode 100644 index 000000000..6a5b2696b --- /dev/null +++ b/src/pages/docs/integrations/coding-agents/augment-code.mdx @@ -0,0 +1,127 @@ +--- +title: "Augment Code (Auggie CLI) session tracing with Future AGI" +description: "Trace Augment's Auggie CLI sessions in Future AGI with Auggie hooks: one trace per conversation, with tool calls, stop causes, and errors. Tool input and output stay off by default, and user email and conversation data are never forwarded." +--- + +## About + +Augment's Auggie CLI runs [hooks](https://docs.augmentcode.com/cli/hooks) at fixed points of a session and passes each one a JSON event on stdin. This page registers the Future AGI [hook-to-OTLP emitter](/docs/integrations/coding-agents/hook-to-otlp) on those hooks, so every Auggie conversation shows up in Future AGI as one trace: + +``` +Auggie session one Auggie conversation (conversation_id), last stop cause +├── launch-process tool call: status, MCP flag +├── view +├── str-replace-editor file-change count and change types +└── Agent stop stop cause (end_turn, interrupted, max_iterations, error) +``` + +Auggie hooks carry no turn id, tool call id, or timing, so tools and stops sit directly under the session in arrival order. + +This is not the same as: + +- **Augment in VS Code or JetBrains.** Augment's settings table says the IDE extensions read `~/.augment/settings.json`, but Augment does not document that they fire the same hook events. Only the CLI is supported here. +- **Augment's Context Engine** as a retrieval product, or the `auggie.log` debug log. Neither is read. + +| | | +| --- | --- | +| Tested with | Auggie CLI 0.36.0 (`@augmentcode/auggie`), macOS. Hook configuration validated with Auggie's own validator; no signed-in session was run (see [Verification status](#verification-status)). | +| Augment docs used | [Hooks](https://docs.augmentcode.com/cli/hooks), read 2026-10-14 | +| Requires | An Augment account signed in to Auggie (`auggie login`). Python 3.9+ on the `PATH` Auggie uses. No packages. | +| Source | [examples/coding-agents/augment-code](https://github.com/future-agi/docs/tree/main/examples/coding-agents/augment-code) and [hook-to-otlp](https://github.com/future-agi/docs/tree/main/examples/coding-agents/hook-to-otlp) | + +## 1. Install the hook + +Clone the examples and run the installer. It copies the emitter, the Augment adapter, and a small `futureagi-hook.sh` wrapper into `~/.augment/fi-hook-to-otlp/`, and writes `~/.augment/settings.json` if you do not have one. If the file exists, the installer leaves it alone and prints the `hooks` entries to merge. + +```bash +git clone --depth 1 https://github.com/future-agi/docs.git fi-docs +fi-docs/examples/coding-agents/augment-code/install.sh +``` + +The hook entries it writes (with your home directory in place of `/Users/you`): + +```json +{ + "hooks": { + "SessionStart": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }], + "PostToolUse": [{ "matcher": ".*", "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }], + "Stop": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }], + "SessionEnd": [{ "hooks": [{ "type": "command", "command": "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh", "timeout": 5000 }] }] + } +} +``` + +- Auggie only runs hook scripts with a `.sh` (or Windows `.ps1`, `.cmd`, `.bat`) extension, so the wrapper starts `python3 emit.py augment`. It discards the emitter's output, because Auggie adds `SessionStart` output to the agent's context, and it always exits 0. +- `timeout` is in milliseconds. The emitter sends in a background process and returns in well under a second. +- No `metadata` block is set. Leave `includeUserContext` and `includeConversationData` off: the adapter ignores the `context` and `conversation` objects anyway, so turning them on only puts your email and conversation text into the hook input on your machine. +- `PreToolUse` is not registered. It is the hook that can block a tool, and without a tool call id it cannot be paired with `PostToolUse`. + +To trace one repository only, put the same entries in `/.augment/settings.local.json` instead (personal, not committed). + +## 2. Add your Future AGI keys + +```bash +mkdir -p ~/.config/fi-hook-to-otlp +cat > ~/.config/fi-hook-to-otlp/env <<'EOF' +FI_API_KEY=your-futureagi-api-key +FI_SECRET_KEY=your-futureagi-secret-key +FI_PROJECT_NAME=auggie-sessions +EOF +chmod 600 ~/.config/fi-hook-to-otlp/env +``` + +Variables set in the environment Auggie runs in take precedence over the file. For a self-hosted Future AGI, also set `FI_BASE_URL` (traces go to `$FI_BASE_URL/tracer/v1/traces`). All settings are listed on the [hook-to-OTLP page](/docs/integrations/coding-agents/hook-to-otlp#configuration). + +## 3. Run a session + +In a repository, run Auggie with a prompt that uses a tool: + +```bash +auggie --print "List the files in this folder and read README.md" +``` + +Open **Observe** in Future AGI and select the project (`auggie-sessions` above). The conversation appears as one trace named **Auggie session**. Later prompts in the same interactive session add more tool spans and another **Agent stop** to the same trace. + +## What is captured + +| Auggie hook | Future AGI span | Fields | +| --- | --- | --- | +| `SessionStart` | **Auggie session** (root) | `session.id` = `conversation_id` | +| `PostToolUse` | tool span named after the tool (`launch-process`, `view`, `str-replace-editor`, `save-file`, `codebase-retrieval`, MCP tool names) | `gen_ai.tool.name`, MCP flag (`is_mcp_tool`), file-change count and change types; status `ERROR` with message `tool error` when `tool_error` is set | +| `Stop` | **Agent stop** | `agent_stop_cause`; status `ERROR` when the cause is `error`. The last cause is also kept on the session span. | +| `SessionEnd` | **Auggie session** end | | + +## What is not available + +- **Turns.** Auggie hooks have no turn id or prompt event in the documented set, so there is no turn span. Each **Agent stop** marks the end of one agent response. +- **Tool duration and tool call ids.** Hooks carry neither, so tool spans have no measured duration and repeated calls of the same tool are told apart only by arrival order. +- **Model name, token counts, and cost.** Not in the hook input. The model display name exists only inside the `includeUserContext` block, which this integration does not use. +- **Prompt and response text.** Only available through `includeConversationData`, which this integration does not use, even with content capture on. +- **Augment IDE extensions, webhooks, and log files.** See [About](#about). + +## Privacy + +By default only structure and metadata leave your machine: the conversation id, tool names, MCP flag, file-change counts and types, stop causes, and statuses. + +- **Not exported by default:** tool input (`tool_input`), tool output (`tool_output`), and tool error text (`tool_error`). +- **Never exported, even with content capture on:** `workspace_roots`; the `context` object (`userEmail`, model display name); the `conversation` object (prompt, response, code); `mcp_metadata`; and file paths and contents from `file_changes`. + +To include tool input, output, and error text, add `FI_HOOK_CAPTURE_CONTENT=1` to the env file. Each field is capped at 4096 characters and common key formats are replaced with `[REDACTED]`. See [Privacy](/docs/integrations/coding-agents/hook-to-otlp#privacy) for details. + +## Verification status + +The configuration above passes the hook-configuration validator shipped inside Auggie 0.36.0, and the payload fields the adapter reads match the ones that build constructs. The adapter was tested end to end with payloads shaped exactly as Augment documents them, sent through `futureagi-hook.sh` into Future AGI. A signed-in Auggie session has not been traced yet: Auggie requires an Augment account before it starts a session or fires any hook. + +## Troubleshooting + +**No trace appears.** +1. Run `auggie --log-level debug --print "..."` and look for `Loaded hooks configuration` and `Hook execution completed` lines. `Invalid hooks configuration` names the field Auggie rejected. +2. Check that `futureagi-hook.sh` is executable (`chmod +x`) and that `python3` resolves for Auggie. +3. Set `FI_HOOK_LOG_FILE=/tmp/fi-hook.log` in `~/.config/fi-hook-to-otlp/env` and run again. No lines: Auggie did not run the wrapper. `error=` lines: the collector is unreachable. `http=401`/`403`: wrong keys. + +**The agent context shows `{}`.** You are running `emit.py` directly as the `SessionStart` command. Use `futureagi-hook.sh`, which discards the output. + +## Next steps + +- [Hook-to-OTLP emitter](/docs/integrations/coding-agents/hook-to-otlp): span model, configuration, and privacy details shared by all hook-based coding agents. +- [Cursor](/docs/integrations/coding-agents/cursor): the same emitter for Cursor Agent sessions. From 2bf1193aef29850bf2fd4fd077f8b0f5033e557c Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 15 Oct 2026 08:53:35 -0700 Subject: [PATCH 2/8] fix(augment): guarded wrapper, safe installer, privacy canaries, page 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//... 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 --- .../augment-code/futureagi-hook.sh | 25 ++- .../coding-agents/augment-code/install.sh | 58 +++-- .../coding-agents/augment-code/run_e2e.sh | 2 +- .../hook-to-otlp/adapters/augment.py | 23 +- .../tests/fixtures/augment/session.jsonl | 6 +- .../tests/test_augment_adapter.py | 57 ++++- .../tests/test_augment_hooks_config.py | 199 ++++++++++++++++++ .../coding-agents/augment-code.mdx | 56 +++-- 8 files changed, 369 insertions(+), 57 deletions(-) create mode 100644 examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py diff --git a/examples/coding-agents/augment-code/futureagi-hook.sh b/examples/coding-agents/augment-code/futureagi-hook.sh index 3e6fe9265..4cea30c87 100755 --- a/examples/coding-agents/augment-code/futureagi-hook.sh +++ b/examples/coding-agents/augment-code/futureagi-hook.sh @@ -1,10 +1,23 @@ #!/bin/sh -# Auggie hook command for Future AGI. Auggie only runs hook scripts with a -# .sh extension, so this wrapper starts the Python emitter. stdout goes to -# /dev/null: Auggie adds SessionStart stdout to the agent's context, and -# this hook has nothing to tell the agent. It always exits 0. -HERE="$(cd "$(dirname "$0")" && pwd)" +# Auggie hook command for Future AGI. +# +# Auggie's documented hook command is a path to a script with a .sh extension, +# which it executes directly (no shell) with the event JSON on stdin. A shell +# guard such as `|| true` in settings.json would therefore not be honoured, so +# the guard lives here: +# - the emitter runs in the canonical guarded subshell, so a missing emit.py, +# a missing python3 or a crash still exits 0; +# - stdout goes to /dev/null: Auggie adds SessionStart output to the agent's +# context and reads Stop output as a possible "block" decision, and this hook +# has nothing to tell the agent; +# - stderr goes to /dev/null, so no Python error text reaches Auggie's logs; +# - -B keeps __pycache__ out of the install folder. +# It uses no external commands, so it works with an empty PATH too. +case "$0" in + */*) HERE="${0%/*}" ;; + *) HERE=. ;; +esac EMIT="$HERE/emit.py" [ -f "$EMIT" ] || EMIT="$HERE/../hook-to-otlp/emit.py" -python3 "$EMIT" augment >/dev/null 2>&1 +(python3 -B "$EMIT" augment 2>/dev/null || true) >/dev/null exit 0 diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh index c0c706cb5..3f7af3d15 100755 --- a/examples/coding-agents/augment-code/install.sh +++ b/examples/coding-agents/augment-code/install.sh @@ -1,19 +1,29 @@ #!/usr/bin/env bash -# Install the Future AGI hook emitter for Augment's Auggie CLI. +# Install the Future AGI hook emitter for Augment's Auggie CLI (macOS, Linux). # -# ./install.sh +# ./install.sh hooks for every Auggie session (~/.augment/settings.json) +# ./install.sh --project REPO hooks for one repository only (REPO/.augment/settings.local.json) # # Copies emit.py, the Augment adapter and the futureagi-hook.sh wrapper into -# ~/.augment/fi-hook-to-otlp/ and writes ~/.augment/settings.json if there is -# none. An existing settings.json is never modified: the script prints the -# "hooks" entries to merge instead. No metadata flags are set, so Auggie does -# not add user context or conversation data to the hook input. +# ~/.augment/fi-hook-to-otlp/. Then writes the hooks file if it does not exist. +# An existing settings file is never modified: the script prints the "hooks" +# entries to merge instead. No metadata flags are set, so Auggie does not add +# user context or conversation data to the hook input. set -euo pipefail +usage() { echo "usage: $0 [--project REPO]" >&2; exit 2; } + HERE="$(cd "$(dirname "$0")" && pwd)" EMITTER="$HERE/../hook-to-otlp" -AUGMENT_DIR="$HOME/.augment" -DEST="$AUGMENT_DIR/fi-hook-to-otlp" +DEST="$HOME/.augment/fi-hook-to-otlp" +SETTINGS="$HOME/.augment/settings.json" +case "${1:-}" in + "") [[ $# -eq 0 ]] || usage ;; + --project) + [[ $# -eq 2 && -d "$2" ]] || usage + SETTINGS="$(cd "$2" && pwd)/.augment/settings.local.json" ;; + *) usage ;; +esac mkdir -p "$DEST/adapters" cp "$EMITTER/emit.py" "$DEST/emit.py" @@ -22,13 +32,33 @@ cp "$HERE/futureagi-hook.sh" "$DEST/futureagi-hook.sh" chmod +x "$DEST/futureagi-hook.sh" echo "emitter: $DEST" -SETTINGS="$(sed "s#/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh#$DEST/futureagi-hook.sh#g" "$HERE/settings.json")" -if [[ -e "$AUGMENT_DIR/settings.json" ]]; then - echo "kept existing $AUGMENT_DIR/settings.json; merge these entries into its \"hooks\" object:" - echo "$SETTINGS" +# settings.json with the wrapper path filled in. Built with json.dump, so any +# character in the home directory gives valid JSON. Auggie splits a command +# that contains a space, and runs one that contains a shell metacharacter +# through bash, so such a path is single-quoted (Auggie removes the quotes). +HOOKS="$(python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' +import json, re, sys +template, wrapper = sys.argv[1], sys.argv[2] +if not re.fullmatch(r"[A-Za-z0-9_./+@:,=%-]+", wrapper): + if "'" in wrapper: + sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") + wrapper = f"'{wrapper}'" +with open(template, encoding="utf-8") as f: + settings = json.load(f) +for groups in settings["hooks"].values(): + for group in groups: + for hook in group["hooks"]: + hook["command"] = wrapper +print(json.dumps(settings, indent=2)) +PY +)" +if [[ -e "$SETTINGS" ]]; then + echo "kept existing $SETTINGS; merge these entries into its \"hooks\" object:" + echo "$HOOKS" else - echo "$SETTINGS" > "$AUGMENT_DIR/settings.json" - echo "hooks: $AUGMENT_DIR/settings.json" + mkdir -p "$(dirname "$SETTINGS")" + echo "$HOOKS" > "$SETTINGS" + echo "hooks: $SETTINGS" fi echo diff --git a/examples/coding-agents/augment-code/run_e2e.sh b/examples/coding-agents/augment-code/run_e2e.sh index bac4bb3df..fa70688a1 100755 --- a/examples/coding-agents/augment-code/run_e2e.sh +++ b/examples/coding-agents/augment-code/run_e2e.sh @@ -34,6 +34,6 @@ PY sleep "${REPLAY_SLEEP:-0.3}" done -TRACE_ID="$(cd "$EMITTER" && python3 -c 'import sys, emit; print(emit.trace_id("augment", sys.argv[1]))' "$RUN_ID")" +TRACE_ID="$(cd "$EMITTER" && python3 -B -c 'import sys, emit; print(emit.trace_id("augment", sys.argv[1]))' "$RUN_ID")" echo "conversation_id=$RUN_ID" echo "trace_id=$TRACE_ID" diff --git a/examples/coding-agents/hook-to-otlp/adapters/augment.py b/examples/coding-agents/hook-to-otlp/adapters/augment.py index 232de01f1..f0b423655 100644 --- a/examples/coding-agents/hook-to-otlp/adapters/augment.py +++ b/examples/coding-agents/hook-to-otlp/adapters/augment.py @@ -11,20 +11,33 @@ Mapped events: - SessionStart -> session start (root span exported, re-exported later) + SessionStart -> opens the session (the root span is sent with the first + child span; an empty session exports nothing) PostToolUse -> tool span (ERROR when tool_error is set) tool_input / tool_output / tool_error = content Stop -> event span "Agent stop" (ERROR when the cause is "error"); the last cause is also kept on the session SessionEnd -> session end -``PreToolUse`` is not mapped: without a tool call id it cannot be paired -with ``PostToolUse``, and it is the one hook that can block a tool. +``PreToolUse`` is deliberately not registered or mapped: it is the hook that +can block a tool, and tracing never takes part in approving or blocking. As a +result tool spans have no measured duration. + +``Stop`` carries ``agent_stop_cause``: ``end_turn``, ``interrupted``, +``max_iterations``, ``error`` (documented) and ``empty_completion`` (0.36.0, +undocumented). Every cause is recorded as-is; only ``error`` sets ERROR. Never exported, even with content capture on: ``workspace_roots``, the ``context`` object (``includeUserContext``: user email, model display name), -the ``conversation`` object (``includeConversationData``), ``mcp_metadata``, -and file contents from ``file_changes`` (only the count and change types). +the ``conversation`` object (``includeConversationData``), ``user_prompt`` +(0.36.0 adds it to tool events when ``includeConversationData`` is on), +``_exchange`` (0.36.0 passes this internal object on ``Stop``), +``mcp_metadata``, and file paths and contents from ``file_changes`` (only the +count and change types). MCP tool names are ``_``, so the MCP +server name is exported as part of the tool name. + +With content capture off, a tool error exports only the fixed status message +``tool error``; the ``tool_error`` text is content. """ from __future__ import annotations diff --git a/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl index d358f901f..8690ed8bf 100644 --- a/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl +++ b/examples/coding-agents/hook-to-otlp/tests/fixtures/augment/session.jsonl @@ -1,10 +1,10 @@ {"event": "SessionStart", "payload": {"hook_event_name": "SessionStart", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} {"event": "PreToolUse", "payload": {"hook_event_name": "PreToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "is_mcp_tool": false}} -{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG README.md", "is_mcp_tool": false, "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "launch-process", "tool_input": {"command": "TOOL_INPUT_MARKER_AUG ls -la"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG README.md", "is_mcp_tool": false, "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "user_prompt": "PROMPT_CANARY_AUG list the files"}} {"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "README.md"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG # demo", "is_mcp_tool": false}} {"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "str-replace-editor", "tool_input": {"path": "src/auth.ts", "old_str_1": "TOOL_INPUT_MARKER_AUG old", "new_str_1": "TOOL_INPUT_MARKER_AUG new"}, "tool_output": "File edited successfully", "is_mcp_tool": false, "file_changes": [{"path": "src/auth.ts", "changeType": "edit", "content": "FILE_CONTENT_CANARY new", "oldContent": "FILE_CONTENT_CANARY old"}]}} -{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "search_example-server", "tool_input": {"query": "TOOL_INPUT_MARKER_AUG docs"}, "tool_error": "ERROR_MARKER_AUG permission denied", "is_mcp_tool": true, "mcp_metadata": {"mcpDecision": "yes", "mcpExecutedToolServerName": "MCP_SERVER_CANARY"}}} -{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "end_turn", "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "conversation": {"userPrompt": "CONVERSATION_CANARY prompt", "agentTextResponse": "CONVERSATION_CANARY reply", "agentCodeResponse": [{"path": "src/auth.ts", "changeType": "edit", "content": "CONVERSATION_CANARY code"}]}}} +{"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "search_example-server", "tool_input": {"query": "TOOL_INPUT_MARKER_AUG docs"}, "tool_error": "ERROR_MARKER_AUG permission denied: /Users/fixtureuser/project/.env", "is_mcp_tool": true, "mcp_metadata": {"timestamp": "2026-10-14T10:31:00-08:00", "mcpDecision": "yes", "mcpTotalToolsCount": 7319, "mcpExecutedToolName": "search_example-server", "mcpExecutedToolServerName": "example-server", "mcpExecutedToolServerToolsCount": 6}}} +{"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "end_turn", "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}, "conversation": {"userPrompt": "CONVERSATION_CANARY prompt", "agentTextResponse": "CONVERSATION_CANARY reply", "agentCodeResponse": [{"path": "src/auth.ts", "changeType": "edit", "content": "CONVERSATION_CANARY code"}]}, "_exchange": {"request_message": "EXCHANGE_CANARY prompt", "response_text": "EXCHANGE_CANARY reply"}}} {"event": "PostToolUse", "payload": {"hook_event_name": "PostToolUse", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "tool_name": "view", "tool_input": {"path": "src/auth.ts"}, "tool_output": "TOOL_OUTPUT_MARKER_AUG body", "is_mcp_tool": false}} {"event": "Stop", "payload": {"hook_event_name": "Stop", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "agent_stop_cause": "error"}} {"event": "SessionEnd", "payload": {"hook_event_name": "SessionEnd", "conversation_id": "fixture-conv-aug-0001", "workspace_roots": ["/Users/fixture/project"], "context": {"userEmail": "fixture.user@example.com", "modelName": "MODEL_LABEL_CANARY", "toolVersion": "0.36.0", "timestamp": "2026-10-14T10:30:00-08:00"}}} diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py index 0b12d5257..429923398 100644 --- a/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_adapter.py @@ -1,8 +1,11 @@ """Auggie CLI adapter contract tests against payloads shaped as https://docs.augmentcode.com/cli/hooks documents them. The fixture turns on every opt-in metadata block Auggie offers -(``context``, ``conversation``, ``mcp_metadata``, ``file_changes``) to prove -the adapter drops them. +(``context``, ``conversation``, ``mcp_metadata``, ``file_changes``) and adds +the two undocumented fields the 0.36.0 bundle can put in the hook input +(``user_prompt`` on tool events, ``_exchange`` on ``Stop``), to prove the +adapter drops them. The MCP tool follows Augment's ``_`` +naming, so the server name is (by design) part of the exported tool name. """ from __future__ import annotations @@ -14,14 +17,23 @@ import emit from adapters import augment -from adapters.base import SESSION, TURN +from adapters.base import ERROR, OK, SESSION, TURN SESSION_FIXTURE = FIXTURES / "augment" / "session.jsonl" SID = "fixture-conv-aug-0001" MARKERS = ("TOOL_INPUT_MARKER_AUG", "TOOL_OUTPUT_MARKER_AUG", "ERROR_MARKER_AUG") # Never exported, even with content capture on (R-03, R-04, section 12). NEVER = ("fixture.user@example.com", "MODEL_LABEL_CANARY", "CONVERSATION_CANARY", - "FILE_CONTENT_CANARY", "MCP_SERVER_CANARY", "/Users/fixture/project") + "FILE_CONTENT_CANARY", "PROMPT_CANARY_AUG", "EXCHANGE_CANARY", "/Users/fixture/project") +# tool_error text in the fixture: a home path with a user name. +ERROR_USER = "fixtureuser" +MCP_TOTAL_TOOLS = 7319 # mcp_metadata.mcpTotalToolsCount in the fixture + + +def all_attribute_values(spans): + for span in spans: + for item in span.get("attributes", []): + yield item["key"], next(iter(item["value"].values())) class AugmentAdapterTest(unittest.TestCase): @@ -70,22 +82,51 @@ def test_stop_cause_and_error(self): self.assertEqual(stops[0]["status"]["code"], 1) self.assertEqual(stops[1]["status"], {"code": 2, "message": "agent stopped with error"}) + def test_every_0_36_0_stop_cause_is_recorded_as_is(self): + # 0.36.0 enum: interrupted, end_turn, max_iterations, empty_completion (undocumented), error. + for cause in ("interrupted", "end_turn", "max_iterations", "empty_completion", "error"): + stop, update = augment.parse("Stop", {"hook_event_name": "Stop", "conversation_id": SID, + "agent_stop_cause": cause}) + self.assertEqual(stop.attributes, {"augment.stop.cause": cause}) + self.assertEqual(stop.status, ERROR if cause == "error" else OK, cause) + self.assertEqual(update.attributes, {"augment.stop.last_cause": cause}) + def test_pre_tool_use_is_not_mapped(self): self.assertEqual(augment.parse("PreToolUse", self.records[1]["payload"]), []) def test_default_export_has_no_content_or_pii(self): - encoded = json.dumps(self.spans()) - for marker in MARKERS + NEVER: + spans = self.spans() + encoded = json.dumps(spans) + for marker in MARKERS + NEVER + (ERROR_USER, "/Users/"): self.assertNotIn(marker, encoded, marker) + def test_error_text_with_a_path_and_user_name_is_content(self): + mcp = by_name(self.spans(), "search_example-server")[0] + self.assertEqual(mcp["status"]["message"], "tool error") # fixed text, never the error + self.assertNotIn("exception.message", attrs(mcp)) + captured = attrs(by_name(self.spans(capture=True), "search_example-server")[0]) + self.assertIn("ERROR_MARKER_AUG permission denied: /Users//project/.env", captured["exception.message"]) + self.assertNotIn(ERROR_USER, json.dumps(captured)) + + def test_mcp_server_is_only_in_the_tool_name(self): + # Augment names MCP tools _: the server name goes out in the tool name, + # nothing else from mcp_metadata does. + for capture in (False, True): + spans = self.spans(capture=capture) + mcp = attrs(by_name(spans, "search_example-server")[0]) + self.assertEqual(mcp["gen_ai.tool.name"], "search_example-server") + for key, value in all_attribute_values(spans): + self.assertNotIn("mcp_metadata", key) + self.assertNotIn(str(MCP_TOTAL_TOOLS), str(value), key) + if key not in ("gen_ai.tool.name", "augment.tool.name", "input.value"): + self.assertNotIn("example-server", str(value), key) + def test_capture_content_opt_in_still_drops_metadata_blocks(self): spans = self.spans(capture=True) encoded = json.dumps(spans) for marker in MARKERS: self.assertIn(marker, encoded, marker) for marker in NEVER: - if marker == "/Users/fixture/project": - continue # not present in any content field of this fixture either self.assertNotIn(marker, encoded, marker) mcp = attrs(by_name(spans, "search_example-server")[0]) self.assertIn("ERROR_MARKER_AUG", mcp["exception.message"]) diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py new file mode 100644 index 000000000..cb43a6a22 --- /dev/null +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py @@ -0,0 +1,199 @@ +"""The shipped Auggie hooks must never block or steer Auggie, with or without the emitter. + +How Auggie 0.36.0 runs a hook command on macOS/Linux (read from the @augmentcode/auggie bundle, +functions dao/QIt/cao/E7n and vao; Augment documents the command as "path to the script"): + +- A command with no shell metacharacter is executed directly (spawn, shell: false). If it contains + a space it is first split into words, honouring single and double quotes. +- A command that starts with ``~`` or contains one of ``| & ; > < $ ` `` runs as ``bash -c ``. +- The event JSON is written to the process's stdin. Exit code 2 blocks only on PreToolUse; any + other non-zero exit, or a command that cannot be started, is logged and the session continues. + Exit 0 stdout is read as JSON (SessionStart output is added to the agent's context, a Stop + ``{"decision": "block"}`` keeps the agent working), so the hook must print nothing. + +The documented command is a ``.sh`` path executed without a shell, so a ``|| true`` guard in +settings.json would not be honoured. The guard is in futureagi-hook.sh, which runs +``(python3 -B emit.py augment 2>/dev/null || true) >/dev/null`` and exits 0. These tests run +every shipped command the way Auggie does, and also through ``sh -c`` with the payload on stdin +and as a trailing heredoc, with the emitter installed, with emit.py missing and with python3 +missing. If the whole install folder is deleted, Auggie cannot start the wrapper; 0.36.0 logs +that as a failed hook and continues (none of the registered events can block). +""" +from __future__ import annotations + +import json +import os +import re +import subprocess +import tempfile +import unittest +from pathlib import Path + +from tests.helpers import Receiver, attrs + +EXAMPLE = Path(__file__).resolve().parents[2] / "augment-code" +TEMPLATE_COMMAND = "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh" +OBSERVE_EVENTS = ["SessionStart", "PostToolUse", "Stop", "SessionEnd"] +SHELLS = [sh for sh in ("/bin/sh", "/bin/bash", "/bin/zsh", "/bin/dash") if os.path.exists(sh)] +# Home directories that break naive quoting: a space, JSON and sed specials, shell specials. +HOMES = ["home", "my home", "odd &#\"\\$HOME`x`"] + +_META = re.compile(r"[|&;><$`]") +_WORDS = re.compile(r'"([^"]*(?:\\.[^"]*)*)"|\'([^\']*(?:\\.[^\']*)*)\'|(\S+)') + + +def auggie_argv(command, args=()): + """Port of Auggie 0.36.0's POSIX command resolution (dao, QIt, E7n, cao).""" + if command.startswith("~") or (not args and _META.search(command)): + return ["bash", "-c", f"{command} {' '.join(args)}" if args else command] + if not args and " " in command: + words = [next(g for g in m.groups() if g is not None) for m in _WORDS.finditer(command)] + return words or [command] + return [command, *args] + + +def commands(settings): + return [(event, hook) for event, groups in settings["hooks"].items() + for group in groups for hook in group["hooks"]] + + +def payload(event, sid, cwd): + body = {"hook_event_name": event, "conversation_id": sid, "workspace_roots": [str(cwd)]} + if event == "PostToolUse": + body.update(tool_name="view", tool_input={"path": "README.md"}, + tool_output="it's $HOME `id` \"quoted\" OUTPUT_MARK", is_mcp_tool=False) + if event == "Stop": + body["agent_stop_cause"] = "end_turn" + return body + + +def run_hook(command, body, env, cwd, transport, shell="/bin/sh"): + text = json.dumps(body, indent=2) # Auggie serializes the event with indent 2 + if transport == "auggie": + argv = auggie_argv(command) + return subprocess.run(argv, cwd=cwd, input=text, capture_output=True, text=True, env=env, + timeout=30) + if transport == "stdin": + return subprocess.run([shell, "-c", command], cwd=cwd, input=text, capture_output=True, + text=True, env=env, timeout=30) + script = f"{command} <<'AUGGIE_HOOK_EOF'\n{text}\nAUGGIE_HOOK_EOF" + return subprocess.run([shell, "-c", script], cwd=cwd, stdin=subprocess.DEVNULL, + capture_output=True, text=True, env=env, timeout=30) + + +def shells_without_python(tmp): + """A PATH with sh and bash but no python3.""" + bin_dir = Path(tmp, "no-python-bin") + bin_dir.mkdir() + for name in ("sh", "bash"): + os.symlink(f"/bin/{name}", bin_dir / name) + return str(bin_dir) + + +class AugmentHooksConfigTest(unittest.TestCase): + def base_env(self, home, **extra): + env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin"), "HOME": str(home)} + env.update(extra) + return env + + def install(self, tmp, home_name, *args): + home = Path(tmp, home_name) + home.mkdir() + result = subprocess.run([str(EXAMPLE / "install.sh"), *args], capture_output=True, text=True, + env=self.base_env(home)) + self.assertEqual(result.returncode, 0, result.stderr) + return home + + def test_template_registers_observation_hooks_only(self): + settings = json.loads((EXAMPLE / "settings.json").read_text()) + self.assertEqual(list(settings["hooks"]), OBSERVE_EVENTS) # never PreToolUse + for event, hook in commands(settings): + self.assertEqual(hook, {"type": "command", "command": TEMPLATE_COMMAND, "timeout": 5000}, event) + self.assertNotIn("metadata", json.dumps(settings)) # no includeUserContext / ConversationData + + def test_installed_commands_send_the_payload_and_print_nothing(self): + with tempfile.TemporaryDirectory() as tmp: + project = Path(tmp, "project") + project.mkdir() + for home_name in HOMES: + home = self.install(tmp, home_name) + wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" + settings = json.loads((home / ".augment" / "settings.json").read_text()) + runs = [("auggie", "/bin/sh"), ("stdin", "/bin/sh"), ("heredoc", "/bin/sh")] + if home_name == "home": + runs += [(t, sh) for sh in SHELLS for t in ("stdin", "heredoc")] + for transport, shell in runs: + label = f"{home_name!r} {transport} {shell}" + for _event, hook in commands(settings): + argv = auggie_argv(hook["command"]) + self.assertIn(str(wrapper), argv[-1] if argv[0] == "bash" else argv[0], label) + rx = Receiver() + try: + sid = f"cfg-{len(home_name)}-{transport}-{Path(shell).name}" + env = self.base_env(home, FI_API_KEY="k", FI_SECRET_KEY="s", FI_HOOK_SYNC="1", + FI_HOOK_CAPTURE_CONTENT="1", + FI_OTLP_ENDPOINT=rx.url + "/tracer/v1/traces", + FI_HOOK_STATE_DIR=str(Path(tmp, f"state-{sid}"))) + for event, hook in commands(settings): + result = run_hook(hook["command"], payload(event, sid, project), env, project, + transport, shell) + self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "", ""), + f"{label} {event}") + spans = rx.spans() + finally: + rx.close() + names = {s["name"] for s in spans} + self.assertTrue({"view", "Agent stop", "Auggie session"} <= names, f"{label}: {names}") + view = [s for s in spans if s["name"] == "view"][-1] + self.assertEqual(attrs(view)["session.id"], sid, label) + # The heredoc is quoted: no expansion of $HOME, backticks or quotes on the way in. + self.assertEqual(attrs(view)["output.value"], payload("PostToolUse", sid, project)["tool_output"], + label) + self.assertEqual(list(home.rglob("__pycache__")), [], "-B keeps bytecode out") + + def test_missing_emitter_or_python_exits_0_with_no_output(self): + with tempfile.TemporaryDirectory() as tmp: + home = self.install(tmp, "home") + (home / ".augment" / "fi-hook-to-otlp" / "emit.py").unlink() + settings = json.loads((home / ".augment" / "settings.json").read_text()) + no_python = shells_without_python(tmp) + for path_label, path in (("emit.py missing", None), ("python3 missing", no_python)): + env = self.base_env(home, **({"PATH": path} if path else {})) + for shell in SHELLS: + for transport in ("auggie", "stdin", "heredoc"): + if transport == "auggie" and shell != SHELLS[0]: + continue + for event, hook in commands(settings): + result = run_hook(hook["command"], payload(event, "cfg-missing", tmp), env, tmp, + transport, shell) + self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "", ""), + f"{path_label} {shell} {transport} {event}") + + def test_project_install_writes_only_the_workspace_file(self): + with tempfile.TemporaryDirectory() as tmp: + repo = Path(tmp, "repo") + repo.mkdir() + home = self.install(tmp, "home", "--project", str(repo)) + local = repo / ".augment" / "settings.local.json" + self.assertTrue(local.exists()) + self.assertFalse((home / ".augment" / "settings.json").exists()) + wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" + for _event, hook in commands(json.loads(local.read_text())): + self.assertEqual(auggie_argv(hook["command"]), [str(wrapper)]) + + def test_existing_settings_file_is_never_modified(self): + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + (home / ".augment").mkdir(parents=True) + existing = home / ".augment" / "settings.json" + existing.write_text('{"model": "keep-me"}\n') + result = subprocess.run([str(EXAMPLE / "install.sh")], capture_output=True, text=True, + env=self.base_env(home)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(existing.read_text(), '{"model": "keep-me"}\n') + self.assertIn("merge these entries", result.stdout) + self.assertIn(str(home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh"), result.stdout) + + +if __name__ == "__main__": + unittest.main() diff --git a/src/pages/docs/integrations/coding-agents/augment-code.mdx b/src/pages/docs/integrations/coding-agents/augment-code.mdx index 6a5b2696b..19d1591cd 100644 --- a/src/pages/docs/integrations/coding-agents/augment-code.mdx +++ b/src/pages/docs/integrations/coding-agents/augment-code.mdx @@ -12,7 +12,7 @@ Auggie session one Auggie conversation (conversation_id), last stop c ├── launch-process tool call: status, MCP flag ├── view ├── str-replace-editor file-change count and change types -└── Agent stop stop cause (end_turn, interrupted, max_iterations, error) +└── Agent stop stop cause (end_turn, interrupted, max_iterations, empty_completion, error) ``` Auggie hooks carry no turn id, tool call id, or timing, so tools and stops sit directly under the session in arrival order. @@ -20,11 +20,11 @@ Auggie hooks carry no turn id, tool call id, or timing, so tools and stops sit d This is not the same as: - **Augment in VS Code or JetBrains.** Augment's settings table says the IDE extensions read `~/.augment/settings.json`, but Augment does not document that they fire the same hook events. Only the CLI is supported here. -- **Augment's Context Engine** as a retrieval product, or the `auggie.log` debug log. Neither is read. +- **Augment's Context Engine** as a retrieval product, or Auggie's debug log file. Neither is read. | | | | --- | --- | -| Tested with | Auggie CLI 0.36.0 (`@augmentcode/auggie`), macOS. Hook configuration validated with Auggie's own validator; no signed-in session was run (see [Verification status](#verification-status)). | +| Tested with | Auggie CLI 0.36.0 (`@augmentcode/auggie`), macOS. Hook configuration validated with Auggie's own validator; no signed-in session was run (see [Verification status](#verification-status)). Linux uses the same commands but was not tested. Windows is not supported: the hook is a `.sh` script and the installer needs bash. | | Augment docs used | [Hooks](https://docs.augmentcode.com/cli/hooks), read 2026-10-14 | | Requires | An Augment account signed in to Auggie (`auggie login`). Python 3.9+ on the `PATH` Auggie uses. No packages. | | Source | [examples/coding-agents/augment-code](https://github.com/future-agi/docs/tree/main/examples/coding-agents/augment-code) and [hook-to-otlp](https://github.com/future-agi/docs/tree/main/examples/coding-agents/hook-to-otlp) | @@ -51,12 +51,20 @@ The hook entries it writes (with your home directory in place of `/Users/you`): } ``` -- Auggie only runs hook scripts with a `.sh` (or Windows `.ps1`, `.cmd`, `.bat`) extension, so the wrapper starts `python3 emit.py augment`. It discards the emitter's output, because Auggie adds `SessionStart` output to the agent's context, and it always exits 0. +- Augment documents a hook command as the path to a script with a `.sh` extension (or Windows `.ps1`, `.cmd`, `.bat`), and Auggie runs that script directly, not through a shell. So the guard that other coding-agent pages put in the hook command lives inside `futureagi-hook.sh`: it runs `(python3 -B emit.py augment 2>/dev/null || true)` with its output discarded, and always exits 0. A missing `emit.py`, a missing `python3`, or an emitter crash therefore never reaches Auggie as an error or as output. +- The wrapper prints nothing. That matters for two of these hooks: Auggie adds `SessionStart` output to the agent's context, and reads `{"decision": "block"}` on `Stop` as "keep working". With no output, `Stop` is observed and never blocked. +- If your home directory contains a space or a shell character, the installer single-quotes the path, which Auggie accepts. - `timeout` is in milliseconds. The emitter sends in a background process and returns in well under a second. -- No `metadata` block is set. Leave `includeUserContext` and `includeConversationData` off: the adapter ignores the `context` and `conversation` objects anyway, so turning them on only puts your email and conversation text into the hook input on your machine. -- `PreToolUse` is not registered. It is the hook that can block a tool, and without a tool call id it cannot be paired with `PostToolUse`. +- No `metadata` block is set. Leave `includeUserContext` and `includeConversationData` off: the adapter ignores the `context`, `conversation`, and `user_prompt` fields anyway, so turning them on only adds your email and conversation text to the hook input on your machine. +- `PreToolUse` is deliberately not registered: it is the hook that can block a tool, and tracing never takes part in approving or blocking. As a result, tool spans have no measured duration. -To trace one repository only, put the same entries in `/.augment/settings.local.json` instead (personal, not committed). +`~/.augment/settings.json` is also read by the Augment VS Code and JetBrains extensions. To trace one repository only, and keep the hooks out of that shared file, install into the repository's workspace settings instead, which only the CLI reads: + +```bash +fi-docs/examples/coding-agents/augment-code/install.sh --project /path/to/your/repo +``` + +This writes `/.augment/settings.local.json` (personal, not committed) and leaves `~/.augment/settings.json` alone. If you installed the user-level hooks earlier, remove their entries from `~/.augment/settings.json`, otherwise every repository is still traced. (Auggie 0.36.0 runs an identical hook command only once when several settings files register it, so keeping both does not send tool calls twice.) ## 2. Add your Future AGI keys @@ -86,42 +94,50 @@ Open **Observe** in Future AGI and select the project (`auggie-sessions` above). | Auggie hook | Future AGI span | Fields | | --- | --- | --- | -| `SessionStart` | **Auggie session** (root) | `session.id` = `conversation_id` | -| `PostToolUse` | tool span named after the tool (`launch-process`, `view`, `str-replace-editor`, `save-file`, `codebase-retrieval`, MCP tool names) | `gen_ai.tool.name`, MCP flag (`is_mcp_tool`), file-change count and change types; status `ERROR` with message `tool error` when `tool_error` is set | -| `Stop` | **Agent stop** | `agent_stop_cause`; status `ERROR` when the cause is `error`. The last cause is also kept on the session span. | +| `SessionStart` | **Auggie session** (root) | `session.id` = `conversation_id`. The root span is sent with the first tool or stop span; a session with no activity sends nothing. | +| `PostToolUse` | tool span named after the tool (`launch-process`, `view`, `str-replace-editor`, `save-file`, `codebase-retrieval`, MCP tool names) | `gen_ai.tool.name`, MCP flag (`is_mcp_tool`), file-change count and change types; status `ERROR` when `tool_error` is set, with the message `tool error` (with content capture on, the error text) | +| `Stop` | **Agent stop** | `agent_stop_cause`; status `ERROR` when the cause is `error`. The last cause is also kept on the session span. Auggie 0.36.0 can also report `empty_completion` (not in Augment's docs); it is recorded as-is with status OK. | | `SessionEnd` | **Auggie session** end | | ## What is not available -- **Turns.** Auggie hooks have no turn id or prompt event in the documented set, so there is no turn span. Each **Agent stop** marks the end of one agent response. -- **Tool duration and tool call ids.** Hooks carry neither, so tool spans have no measured duration and repeated calls of the same tool are told apart only by arrival order. +- **Turns.** Auggie hooks have no turn id or prompt event in the documented set, so there is no turn span. Each **Agent stop** marks the end of one agent response. (Auggie 0.36.0 also accepts an undocumented `PromptSubmit` hook, which carries the prompt text; it is not used.) +- **Tool duration and tool call ids.** `PostToolUse` carries neither, and `PreToolUse` (which would mark the start) is not registered because it can block tools. Tool spans have no measured duration, and repeated calls of the same tool are told apart only by arrival order. - **Model name, token counts, and cost.** Not in the hook input. The model display name exists only inside the `includeUserContext` block, which this integration does not use. -- **Prompt and response text.** Only available through `includeConversationData`, which this integration does not use, even with content capture on. +- **Prompt and response text.** Not forwarded, even with content capture on. - **Augment IDE extensions, webhooks, and log files.** See [About](#about). ## Privacy -By default only structure and metadata leave your machine: the conversation id, tool names, MCP flag, file-change counts and types, stop causes, and statuses. +By default only structure and metadata leave your machine: the conversation id, tool names, MCP flag, file-change counts and types, stop causes, and statuses. A failed tool is marked with the fixed message `tool error`, never with the error text. -- **Not exported by default:** tool input (`tool_input`), tool output (`tool_output`), and tool error text (`tool_error`). -- **Never exported, even with content capture on:** `workspace_roots`; the `context` object (`userEmail`, model display name); the `conversation` object (prompt, response, code); `mcp_metadata`; and file paths and contents from `file_changes`. +- **Not exported by default**: tool input (`tool_input`), tool output (`tool_output`), and tool error text (`tool_error`). +- **Never exported, even with content capture on**: `workspace_roots`; the `context` object (`userEmail`, model display name); the `conversation` object (prompt, response, code); `user_prompt`, which Auggie 0.36.0 adds to tool events when `includeConversationData` is on; `_exchange`, an internal object Auggie 0.36.0 passes on `Stop`; `mcp_metadata`; and file paths and contents from `file_changes`. +- **MCP server names.** Augment names MCP tools `_`, so the server name is exported as part of the tool name. -To include tool input, output, and error text, add `FI_HOOK_CAPTURE_CONTENT=1` to the env file. Each field is capped at 4096 characters and common key formats are replaced with `[REDACTED]`. See [Privacy](/docs/integrations/coding-agents/hook-to-otlp#privacy) for details. +To include tool input, output, and error text, add `FI_HOOK_CAPTURE_CONTENT=1` to the env file. Paths inside that content (for example the `path` a `view` call reads, or a path in an error) are then exported too, with the user name in home-directory paths replaced by ``. Each field is capped at 4096 characters and common key formats are replaced with `[REDACTED]`. See [Privacy](/docs/integrations/coding-agents/hook-to-otlp#privacy) for details. ## Verification status -The configuration above passes the hook-configuration validator shipped inside Auggie 0.36.0, and the payload fields the adapter reads match the ones that build constructs. The adapter was tested end to end with payloads shaped exactly as Augment documents them, sent through `futureagi-hook.sh` into Future AGI. A signed-in Auggie session has not been traced yet: Auggie requires an Augment account before it starts a session or fires any hook. +The configuration above passes the hook-configuration validator shipped inside Auggie 0.36.0, and the payload fields the adapter reads match the ones that build constructs. The hook commands were run the way Auggie 0.36.0 runs them, using the command-handling code from its bundle. The adapter was tested end to end with payloads shaped as Augment documents them, sent through `futureagi-hook.sh` into Future AGI. A signed-in Auggie session has not been traced yet: Auggie requires an Augment account before it starts a session or fires any hook. Still to check in a real session: the exact `Stop` payload, and what a resumed conversation (`auggie --continue`) sends. ## Troubleshooting **No trace appears.** -1. Run `auggie --log-level debug --print "..."` and look for `Loaded hooks configuration` and `Hook execution completed` lines. `Invalid hooks configuration` names the field Auggie rejected. +1. Run `auggie --log-level debug --log-file - --print "..."` and look for `Loaded hooks configuration` and `Hook execution completed` lines. `Invalid hooks configuration` names the field Auggie rejected. `--log-level` and `--log-file` are not listed in `auggie --help` in 0.36.0; without `--log-file -`, Auggie writes the log to `augment-log.txt` in your temp directory (`$TMPDIR` on macOS) instead of the terminal. 2. Check that `futureagi-hook.sh` is executable (`chmod +x`) and that `python3` resolves for Auggie. 3. Set `FI_HOOK_LOG_FILE=/tmp/fi-hook.log` in `~/.config/fi-hook-to-otlp/env` and run again. No lines: Auggie did not run the wrapper. `error=` lines: the collector is unreachable. `http=401`/`403`: wrong keys. **The agent context shows `{}`.** You are running `emit.py` directly as the `SessionStart` command. Use `futureagi-hook.sh`, which discards the output. -## Next steps +**A resumed conversation looks wrong.** Resuming with `auggie --continue` or `--resume` has not been verified. If Auggie reuses the conversation id, the new tool spans join the original trace, and the session span restarts at the resume time while the earlier tool spans keep their times. + +## Uninstall + +1. Remove the four hook entries from `~/.augment/settings.json` (or the workspace settings file). To pause tracing without editing settings, set `FI_HOOK_DISABLED=1` in `~/.config/fi-hook-to-otlp/env`. +2. Then delete `~/.augment/fi-hook-to-otlp/`. If you delete the folder first, Auggie reports a failed hook on each event but keeps working: none of these hooks can block it. + +## Next Steps - [Hook-to-OTLP emitter](/docs/integrations/coding-agents/hook-to-otlp): span model, configuration, and privacy details shared by all hook-based coding agents. - [Cursor](/docs/integrations/coding-agents/cursor): the same emitter for Cursor Agent sessions. From 60008c42bcd76716e31e80c9ec89ced96c8056e7 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 15 Oct 2026 12:20:46 -0700 Subject: [PATCH 3/8] fix(augment): keep --project settings out of git, fix guard rationale 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 --- .../augment-code/futureagi-hook.sh | 14 +-- .../coding-agents/augment-code/install.sh | 48 +++++++-- .../tests/test_augment_hooks_config.py | 98 +++++++++++++++++-- .../coding-agents/augment-code.mdx | 12 +-- 4 files changed, 143 insertions(+), 29 deletions(-) diff --git a/examples/coding-agents/augment-code/futureagi-hook.sh b/examples/coding-agents/augment-code/futureagi-hook.sh index 4cea30c87..f8976c5bf 100755 --- a/examples/coding-agents/augment-code/futureagi-hook.sh +++ b/examples/coding-agents/augment-code/futureagi-hook.sh @@ -1,15 +1,15 @@ #!/bin/sh # Auggie hook command for Future AGI. # -# Auggie's documented hook command is a path to a script with a .sh extension, -# which it executes directly (no shell) with the event JSON on stdin. A shell -# guard such as `|| true` in settings.json would therefore not be honoured, so -# the guard lives here: +# Augment documents a hook command as the path to a script with a .sh +# extension, which Auggie runs with the event JSON on stdin. The settings +# therefore name this script, and the guard that other coding-agent pages put +# in the hook command lives here: # - the emitter runs in the canonical guarded subshell, so a missing emit.py, # a missing python3 or a crash still exits 0; -# - stdout goes to /dev/null: Auggie adds SessionStart output to the agent's -# context and reads Stop output as a possible "block" decision, and this hook -# has nothing to tell the agent; +# - stdout goes to /dev/null: Auggie adds plain-text SessionStart output to the +# agent's context and reads a Stop {"decision": "block"} as "keep working", +# and this hook has nothing to tell the agent; # - stderr goes to /dev/null, so no Python error text reaches Auggie's logs; # - -B keeps __pycache__ out of the install folder. # It uses no external commands, so it works with an empty PATH too. diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh index 3f7af3d15..884e54a01 100755 --- a/examples/coding-agents/augment-code/install.sh +++ b/examples/coding-agents/augment-code/install.sh @@ -9,6 +9,11 @@ # An existing settings file is never modified: the script prints the "hooks" # entries to merge instead. No metadata flags are set, so Auggie does not add # user context or conversation data to the hook input. +# +# With --project, the workspace file holds this machine's home path, so it is +# also added to the repository's local exclude list (.git/info/exclude, which +# is never committed) unless git already ignores it. No tracked file such as +# .gitignore is changed. set -euo pipefail usage() { echo "usage: $0 [--project REPO]" >&2; exit 2; } @@ -17,25 +22,45 @@ HERE="$(cd "$(dirname "$0")" && pwd)" EMITTER="$HERE/../hook-to-otlp" DEST="$HOME/.augment/fi-hook-to-otlp" SETTINGS="$HOME/.augment/settings.json" +REPO="" case "${1:-}" in "") [[ $# -eq 0 ]] || usage ;; --project) [[ $# -eq 2 && -d "$2" ]] || usage - SETTINGS="$(cd "$2" && pwd)/.augment/settings.local.json" ;; + REPO="$(cd "$2" && pwd)" + SETTINGS="$REPO/.augment/settings.local.json" ;; *) usage ;; esac -mkdir -p "$DEST/adapters" -cp "$EMITTER/emit.py" "$DEST/emit.py" -cp "$EMITTER/adapters/__init__.py" "$EMITTER/adapters/base.py" "$EMITTER/adapters/augment.py" "$DEST/adapters/" -cp "$HERE/futureagi-hook.sh" "$DEST/futureagi-hook.sh" -chmod +x "$DEST/futureagi-hook.sh" -echo "emitter: $DEST" +# Keep /.augment/settings.local.json out of commits (see the header). +ignore_workspace_settings() { + local repo="$1" rel=".augment/settings.local.json" pattern="**/.augment/settings.local.json" exclude + if ! command -v git >/dev/null 2>&1 || ! git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + echo "note: $repo is not a git work tree; keep $rel out of version control" + return 0 + fi + if git -C "$repo" check-ignore -q -- "$rel"; then + echo "ignored: $rel (already ignored by git)" + return 0 + fi + exclude="$(cd "$repo" && git rev-parse --git-path info/exclude)" + case "$exclude" in /*) ;; *) exclude="$repo/$exclude" ;; esac + mkdir -p "$(dirname "$exclude")" + if [[ -s "$exclude" && -n "$(tail -c 1 "$exclude")" ]]; then echo >> "$exclude"; fi + printf '%s\n' "# Future AGI Auggie hooks: personal settings with this machine's home path" "$pattern" >> "$exclude" + if git -C "$repo" check-ignore -q -- "$rel"; then + echo "ignored: $rel (added to $exclude)" + else + echo "warning: git still tracks $repo/$rel; do not commit it, it contains your home path" >&2 + fi +} # settings.json with the wrapper path filled in. Built with json.dump, so any # character in the home directory gives valid JSON. Auggie splits a command # that contains a space, and runs one that contains a shell metacharacter # through bash, so such a path is single-quoted (Auggie removes the quotes). +# Built before anything is copied, so a path that cannot be registered leaves +# no partial install behind. HOOKS="$(python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' import json, re, sys template, wrapper = sys.argv[1], sys.argv[2] @@ -52,6 +77,14 @@ for groups in settings["hooks"].values(): print(json.dumps(settings, indent=2)) PY )" + +mkdir -p "$DEST/adapters" +cp "$EMITTER/emit.py" "$DEST/emit.py" +cp "$EMITTER/adapters/__init__.py" "$EMITTER/adapters/base.py" "$EMITTER/adapters/augment.py" "$DEST/adapters/" +cp "$HERE/futureagi-hook.sh" "$DEST/futureagi-hook.sh" +chmod +x "$DEST/futureagi-hook.sh" +echo "emitter: $DEST" + if [[ -e "$SETTINGS" ]]; then echo "kept existing $SETTINGS; merge these entries into its \"hooks\" object:" echo "$HOOKS" @@ -60,6 +93,7 @@ else echo "$HOOKS" > "$SETTINGS" echo "hooks: $SETTINGS" fi +if [[ -n "$REPO" ]]; then ignore_workspace_settings "$REPO"; fi echo echo "Credentials: put FI_API_KEY, FI_SECRET_KEY and FI_PROJECT_NAME in" diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py index cb43a6a22..0ec9c3125 100644 --- a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py @@ -8,12 +8,15 @@ - A command that starts with ``~`` or contains one of ``| & ; > < $ ` `` runs as ``bash -c ``. - The event JSON is written to the process's stdin. Exit code 2 blocks only on PreToolUse; any other non-zero exit, or a command that cannot be started, is logged and the session continues. - Exit 0 stdout is read as JSON (SessionStart output is added to the agent's context, a Stop - ``{"decision": "block"}`` keeps the agent working), so the hook must print nothing. + Exit 0 stdout is parsed as JSON (a Stop ``{"decision": "block"}`` keeps the agent working); + stdout that is not JSON is shown to the user, or on SessionStart added to the agent's context. + So the hook must print nothing. -The documented command is a ``.sh`` path executed without a shell, so a ``|| true`` guard in -settings.json would not be honoured. The guard is in futureagi-hook.sh, which runs -``(python3 -B emit.py augment 2>/dev/null || true) >/dev/null`` and exits 0. These tests run +Augment documents the command as the path to a ``.sh`` script, so the shipped settings name a +script and the guard lives in it: futureagi-hook.sh runs +``(python3 -B emit.py augment 2>/dev/null || true) >/dev/null`` and exits 0. (0.36.0 would also +run a guarded one-line command through ``bash -c``, see auggie_argv, but that form is not +documented, so it is not used.) These tests run every shipped command the way Auggie does, and also through ``sh -c`` with the payload on stdin and as a trailing heredoc, with the emitter installed, with emit.py missing and with python3 missing. If the whole install folder is deleted, Auggie cannot start the wrapper; 0.36.0 logs @@ -24,6 +27,7 @@ import json import os import re +import shutil import subprocess import tempfile import unittest @@ -35,6 +39,7 @@ TEMPLATE_COMMAND = "/Users/you/.augment/fi-hook-to-otlp/futureagi-hook.sh" OBSERVE_EVENTS = ["SessionStart", "PostToolUse", "Stop", "SessionEnd"] SHELLS = [sh for sh in ("/bin/sh", "/bin/bash", "/bin/zsh", "/bin/dash") if os.path.exists(sh)] +WORKSPACE_FILE = ".augment/settings.local.json" # Home directories that break naive quoting: a space, JSON and sed specials, shell specials. HOMES = ["home", "my home", "odd &#\"\\$HOME`x`"] @@ -96,14 +101,22 @@ def base_env(self, home, **extra): env.update(extra) return env + def run_install(self, home, *args): + return subprocess.run([str(EXAMPLE / "install.sh"), *args], capture_output=True, text=True, + env=self.base_env(home, GIT_CONFIG_NOSYSTEM="1")) + def install(self, tmp, home_name, *args): home = Path(tmp, home_name) home.mkdir() - result = subprocess.run([str(EXAMPLE / "install.sh"), *args], capture_output=True, text=True, - env=self.base_env(home)) + result = self.run_install(home, *args) self.assertEqual(result.returncode, 0, result.stderr) return home + def git(self, home, repo, *args): + return subprocess.run(["git", "-C", str(repo), "-c", "user.name=t", "-c", "user.email=t@example.com", + *args], capture_output=True, text=True, + env=self.base_env(home, GIT_CONFIG_NOSYSTEM="1")) + def test_template_registers_observation_hooks_only(self): settings = json.loads((EXAMPLE / "settings.json").read_text()) self.assertEqual(list(settings["hooks"]), OBSERVE_EVENTS) # never PreToolUse @@ -173,13 +186,80 @@ def test_project_install_writes_only_the_workspace_file(self): with tempfile.TemporaryDirectory() as tmp: repo = Path(tmp, "repo") repo.mkdir() - home = self.install(tmp, "home", "--project", str(repo)) - local = repo / ".augment" / "settings.local.json" + home = Path(tmp, "home") + home.mkdir() + result = self.run_install(home, "--project", str(repo)) + self.assertEqual(result.returncode, 0, result.stderr) + local = repo / WORKSPACE_FILE self.assertTrue(local.exists()) self.assertFalse((home / ".augment" / "settings.json").exists()) wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" for _event, hook in commands(json.loads(local.read_text())): self.assertEqual(auggie_argv(hook["command"]), [str(wrapper)]) + self.assertIn("is not a git work tree", result.stdout) # nothing to ignore it with + + @unittest.skipUnless(shutil.which("git"), "git not installed") + def test_project_install_keeps_the_workspace_file_out_of_git(self): + """The workspace file holds this machine's home path, so `git add -A` must not pick it up. + + The installer adds it to the repository's local exclude list (never committed) and changes + no tracked file: from a subfolder, from the root, on a re-run and in a linked worktree. + """ + pattern = "**/" + WORKSPACE_FILE + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + home.mkdir() + repo = Path(tmp, "repo") + (repo / "sub").mkdir(parents=True) + self.assertEqual(self.git(home, repo, "init", "-q").returncode, 0) + for target in (repo / "sub", repo, repo): + result = self.run_install(home, "--project", str(target)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(self.git(home, target, "check-ignore", "-q", "--", WORKSPACE_FILE).returncode, + 0, f"{target}: {result.stdout}") + self.assertIn(str(home), (target / WORKSPACE_FILE).read_text()) # why it must stay local + exclude = repo / ".git" / "info" / "exclude" + self.assertEqual(exclude.read_text().count(pattern), 1) + self.assertFalse((repo / ".gitignore").exists()) + self.assertEqual(self.git(home, repo, "status", "--porcelain", "--untracked-files=all").stdout, "") + + # A linked worktree shares the main repository's exclude list. + self.assertEqual(self.git(home, repo, "commit", "-q", "--allow-empty", "-m", "init").returncode, 0) + worktree = Path(tmp, "worktree") + self.assertEqual(self.git(home, repo, "worktree", "add", "-q", str(worktree)).returncode, 0) + exclude.write_text("") + result = self.run_install(home, "--project", str(worktree)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertEqual(self.git(home, worktree, "check-ignore", "-q", "--", WORKSPACE_FILE).returncode, 0) + self.assertEqual(exclude.read_text().count(pattern), 1) + self.assertEqual(self.git(home, worktree, "status", "--porcelain", "--untracked-files=all").stdout, "") + + @unittest.skipUnless(shutil.which("git"), "git not installed") + def test_project_install_leaves_an_existing_ignore_rule_alone(self): + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "home") + home.mkdir() + repo = Path(tmp, "repo") + repo.mkdir() + self.assertEqual(self.git(home, repo, "init", "-q").returncode, 0) + (repo / ".gitignore").write_text(WORKSPACE_FILE + "\n") # what Auggie itself adds + exclude = repo / ".git" / "info" / "exclude" + before = exclude.read_text() + result = self.run_install(home, "--project", str(repo)) + self.assertEqual(result.returncode, 0, result.stderr) + self.assertIn("already ignored", result.stdout) + self.assertEqual(exclude.read_text(), before) + self.assertEqual((repo / ".gitignore").read_text(), WORKSPACE_FILE + "\n") + + def test_unregistrable_home_stops_before_copying(self): + """A home path with a single quote cannot be registered; nothing is installed.""" + with tempfile.TemporaryDirectory() as tmp: + home = Path(tmp, "it's home") + home.mkdir() + result = self.run_install(home) + self.assertEqual(result.returncode, 1) + self.assertIn("single quote", result.stderr) + self.assertEqual(list(home.iterdir()), []) def test_existing_settings_file_is_never_modified(self): with tempfile.TemporaryDirectory() as tmp: diff --git a/src/pages/docs/integrations/coding-agents/augment-code.mdx b/src/pages/docs/integrations/coding-agents/augment-code.mdx index 19d1591cd..3566409e0 100644 --- a/src/pages/docs/integrations/coding-agents/augment-code.mdx +++ b/src/pages/docs/integrations/coding-agents/augment-code.mdx @@ -51,9 +51,9 @@ The hook entries it writes (with your home directory in place of `/Users/you`): } ``` -- Augment documents a hook command as the path to a script with a `.sh` extension (or Windows `.ps1`, `.cmd`, `.bat`), and Auggie runs that script directly, not through a shell. So the guard that other coding-agent pages put in the hook command lives inside `futureagi-hook.sh`: it runs `(python3 -B emit.py augment 2>/dev/null || true)` with its output discarded, and always exits 0. A missing `emit.py`, a missing `python3`, or an emitter crash therefore never reaches Auggie as an error or as output. -- The wrapper prints nothing. That matters for two of these hooks: Auggie adds `SessionStart` output to the agent's context, and reads `{"decision": "block"}` on `Stop` as "keep working". With no output, `Stop` is observed and never blocked. -- If your home directory contains a space or a shell character, the installer single-quotes the path, which Auggie accepts. +- Augment documents a hook command as the path to a script with a `.sh` extension (or Windows `.ps1`, `.cmd`, `.bat`). So the hook command is a script, `futureagi-hook.sh`, and the guard that other coding-agent pages put in the hook command lives inside it: the script runs `(python3 -B emit.py augment 2>/dev/null || true)` with its output discarded, and always exits 0. A missing `emit.py`, a missing `python3`, or an emitter crash therefore never reaches Auggie as an error or as output. +- The wrapper prints nothing, so Auggie has nothing to act on. Auggie adds plain-text `SessionStart` output to the agent's context, and reads `{"decision": "block"}` on `Stop` as "keep working". With no output, `Stop` is observed and never blocked. +- If your home directory contains a space or a shell character, the installer single-quotes the path, which Auggie accepts. A home directory that contains a single quote cannot be registered: the installer stops before copying anything. - `timeout` is in milliseconds. The emitter sends in a background process and returns in well under a second. - No `metadata` block is set. Leave `includeUserContext` and `includeConversationData` off: the adapter ignores the `context`, `conversation`, and `user_prompt` fields anyway, so turning them on only adds your email and conversation text to the hook input on your machine. - `PreToolUse` is deliberately not registered: it is the hook that can block a tool, and tracing never takes part in approving or blocking. As a result, tool spans have no measured duration. @@ -64,7 +64,9 @@ The hook entries it writes (with your home directory in place of `/Users/you`): fi-docs/examples/coding-agents/augment-code/install.sh --project /path/to/your/repo ``` -This writes `/.augment/settings.local.json` (personal, not committed) and leaves `~/.augment/settings.json` alone. If you installed the user-level hooks earlier, remove their entries from `~/.augment/settings.json`, otherwise every repository is still traced. (Auggie 0.36.0 runs an identical hook command only once when several settings files register it, so keeping both does not send tool calls twice.) +This writes `/.augment/settings.local.json` and leaves `~/.augment/settings.json` alone. If you installed the user-level hooks earlier, remove their entries from `~/.augment/settings.json`, otherwise every repository is still traced. (Auggie 0.36.0 runs an identical hook command only once when several settings files register it, so keeping both does not send tool calls twice.) + +The workspace file contains your home directory path, so do not commit it. Unless git already ignores the file, the installer adds it to the repository's `.git/info/exclude`, a local ignore list that is never committed, so `git add -A` skips it. The installer does not change `.gitignore` or any other tracked file. Outside a git repository it only prints a reminder. ## 2. Add your Future AGI keys @@ -128,8 +130,6 @@ The configuration above passes the hook-configuration validator shipped inside A 2. Check that `futureagi-hook.sh` is executable (`chmod +x`) and that `python3` resolves for Auggie. 3. Set `FI_HOOK_LOG_FILE=/tmp/fi-hook.log` in `~/.config/fi-hook-to-otlp/env` and run again. No lines: Auggie did not run the wrapper. `error=` lines: the collector is unreachable. `http=401`/`403`: wrong keys. -**The agent context shows `{}`.** You are running `emit.py` directly as the `SessionStart` command. Use `futureagi-hook.sh`, which discards the output. - **A resumed conversation looks wrong.** Resuming with `auggie --continue` or `--resume` has not been verified. If Auggie reuses the conversation id, the new tool spans join the original trace, and the session span restarts at the resume time while the earlier tool spans keep their times. ## Uninstall From ed52e69d6b0681b8a042548c0d54180822ad25fa Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Tue, 20 Oct 2026 02:56:21 -0700 Subject: [PATCH 4/8] docs(augment): how other tools support Augment, real session-hook verification (TH-8291) Co-Authored-By: Claude Opus 5.5 --- .../coding-agents/augment-code.mdx | 25 +++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/integrations/coding-agents/augment-code.mdx b/src/pages/docs/integrations/coding-agents/augment-code.mdx index 3566409e0..5ec5ddfc6 100644 --- a/src/pages/docs/integrations/coding-agents/augment-code.mdx +++ b/src/pages/docs/integrations/coding-agents/augment-code.mdx @@ -24,7 +24,7 @@ This is not the same as: | | | | --- | --- | -| Tested with | Auggie CLI 0.36.0 (`@augmentcode/auggie`), macOS. Hook configuration validated with Auggie's own validator; no signed-in session was run (see [Verification status](#verification-status)). Linux uses the same commands but was not tested. Windows is not supported: the hook is a `.sh` script and the installer needs bash. | +| Tested with | Auggie CLI 0.36.0 (`@augmentcode/auggie`), macOS. Hook configuration validated with Auggie's own validator; a signed-in session without usage fired the session hooks, but no tools ran (see [Verification status](#verification-status)). Linux uses the same commands but was not tested. Windows is not supported: the hook is a `.sh` script and the installer needs bash. | | Augment docs used | [Hooks](https://docs.augmentcode.com/cli/hooks), read 2026-10-14 | | Requires | An Augment account signed in to Auggie (`auggie login`). Python 3.9+ on the `PATH` Auggie uses. No packages. | | Source | [examples/coding-agents/augment-code](https://github.com/future-agi/docs/tree/main/examples/coding-agents/augment-code) and [hook-to-otlp](https://github.com/future-agi/docs/tree/main/examples/coding-agents/hook-to-otlp) | @@ -119,9 +119,30 @@ By default only structure and metadata leave your machine: the conversation id, To include tool input, output, and error text, add `FI_HOOK_CAPTURE_CONTENT=1` to the env file. Paths inside that content (for example the `path` a `view` call reads, or a path in an error) are then exported too, with the user name in home-directory paths replaced by ``. Each field is capped at 4096 characters and common key formats are replaced with `[REDACTED]`. See [Privacy](/docs/integrations/coding-agents/hook-to-otlp#privacy) for details. +## How other tools support Augment Code + +Augment documents [hooks](https://docs.augmentcode.com/cli/hooks) as its extension point and has no native OpenTelemetry export, so every tool we found (read 2026-10-20) uses hooks. + +| Tool | Augment support | Mechanism | Plan needed | +| --- | --- | --- | --- | +| [Langfuse](https://langfuse.com/integrations/developer-tools/augment-code) | Yes | `PostToolUse` and `Stop` hooks with shell and Python scripts. The final conversation payload gives prompts, responses and tool observations, and content is on by default | An Augment account with usage | +| Braintrust, LangSmith, Arize, Datadog, Honeycomb, Laminar, Opik, Helicone, PostHog, SigNoz, Grafana, New Relic, Dynatrace | No Augment integration found | Augment's own articles on [agent observability](https://www.augmentcode.com/tools/best-ai-agent-observability-tools) cover these tools for generic agent code, not for Auggie | n/a | +| Augment Cosmos | Cloud agent runs are kept as replayable sessions inside Augment | Platform feature, not an export | Augment plan | + +Future AGI's hook setup differs from Langfuse's in three ways: it also registers `SessionStart` and `SessionEnd` (one trace per conversation instead of one trace per tool call), it does not read the conversation payload at all by default, and its hook cannot print to the agent. Langfuse's page shows no way to try the hooks without a model response. + ## Verification status -The configuration above passes the hook-configuration validator shipped inside Auggie 0.36.0, and the payload fields the adapter reads match the ones that build constructs. The hook commands were run the way Auggie 0.36.0 runs them, using the command-handling code from its bundle. The adapter was tested end to end with payloads shaped as Augment documents them, sent through `futureagi-hook.sh` into Future AGI. A signed-in Auggie session has not been traced yet: Auggie requires an Augment account before it starts a session or fires any hook. Still to check in a real session: the exact `Stop` payload, and what a resumed conversation (`auggie --continue`) sends. +The configuration above passes the hook-configuration validator shipped inside Auggie 0.36.0, and the hook commands were run the way Auggie 0.36.0 runs them, using the command-handling code from its bundle. + +| Part | Status | +| --- | --- | +| `SessionStart`, `Stop`, `SessionEnd` payloads | Real. An Auggie 0.36.0 session signed in to an Augment account that had no usage left (2026-10-19) fired all three hooks, in that order, `Stop` once, with `agent_stop_cause: end_turn`. Those three captured payloads were replayed through the installed `settings.json` and `futureagi-hook.sh` into a local Future AGI (2026-10-20) | +| The real `Stop` payload | Carries the internal `_exchange` object, with the prompt text, the response text (which here contained the account email), a request id and the terminal's working directory. None of it reaches Future AGI by default | +| `PostToolUse` payloads | Documented shape only. A session without usage runs no tools, so no real tool payload was captured | +| Not checked | Tool spans from a real session, wrapper latency on a real run, and a resumed conversation (`auggie --continue`) | + +Result for the real payloads: one trace of two spans (`Auggie session` with an `Agent stop` child); the prompt, the response text, the account email, the request id, `_exchange`, `workspace_roots`, the home path, the login name and the host name were in the captured payloads and in none of the stored spans. ## Troubleshooting From 16bbae7ae0d72d4c7af5cd83d4a0e273607b8c46 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 16:35:58 -0800 Subject: [PATCH 5/8] docs(ci): pin compatible Ubuntu runner for browser and hook checks 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 --- .github/workflows/augment-hooks.yml | 2 +- .github/workflows/pr-checks.yml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/augment-hooks.yml b/.github/workflows/augment-hooks.yml index cdd4789c8..d9875eff2 100644 --- a/.github/workflows/augment-hooks.yml +++ b/.github/workflows/augment-hooks.yml @@ -22,7 +22,7 @@ jobs: fail-fast: false matrix: include: - - os: ubuntu-latest + - os: ubuntu-24.04 python: '3.9' - os: macos-26 python: '3.13' diff --git a/.github/workflows/pr-checks.yml b/.github/workflows/pr-checks.yml index 2bb5470c3..446acf9d1 100644 --- a/.github/workflows/pr-checks.yml +++ b/.github/workflows/pr-checks.yml @@ -76,7 +76,8 @@ jobs: docs-build: name: Docs build & Pagefind - runs-on: ubuntu-latest + # Playwright 1.56.1 has no browser/dependency bundle for Ubuntu 26.04. + runs-on: ubuntu-24.04 steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 From 7032c19544967292f3ffd047c8961df384e78006 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 22:25:29 -0800 Subject: [PATCH 6/8] docs(augment): preserve literal paths in Auggie hook dispatch 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 --- .../coding-agents/augment-code/install.sh | 14 +++++---- .../tests/test_augment_hooks_config.py | 31 +++++++++++++------ 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh index 996c508fb..6e066f034 100755 --- a/examples/coding-agents/augment-code/install.sh +++ b/examples/coding-agents/augment-code/install.sh @@ -57,17 +57,19 @@ ignore_workspace_settings() { } # settings.json with the wrapper path filled in. Built with json.dump, so any -# character in the home directory gives valid JSON. Auggie splits a command -# that contains a space, and runs one that contains a shell metacharacter -# through bash, so such a path is single-quoted (Auggie removes the quotes). +# character in the home directory gives valid JSON. Auggie 0.36.0 splits a +# command containing a literal space, or runs one containing |&;><$` through +# bash, so only those paths need single quotes. Other characters (including +# Unicode and parentheses) go straight to spawn: quotes would become part of +# the filename instead of being removed. # Built before anything is copied, so a path that cannot be registered leaves # no partial install behind. HOOKS="$(python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' import json, re, sys template, wrapper = sys.argv[1], sys.argv[2] -if not re.fullmatch(r"[A-Za-z0-9_./+@:,=%-]+", wrapper): - if "'" in wrapper: - sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") +if "'" in wrapper: + sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") +if re.search(r"[ |&;><$`]", wrapper): wrapper = f"'{wrapper}'" with open(template, encoding="utf-8") as f: settings = json.load(f) diff --git a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py index db86e1041..660d0b8ca 100644 --- a/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py +++ b/examples/coding-agents/hook-to-otlp/tests/test_augment_hooks_config.py @@ -16,11 +16,13 @@ script and the guard lives in it: futureagi-hook.sh runs ``(python3 -B emit.py augment 2>/dev/null || true) >/dev/null`` and exits 0. (0.36.0 would also run a guarded one-line command through ``bash -c``, see auggie_argv, but that form is not -documented, so it is not used.) These tests run -every shipped command the way Auggie does, and also through ``sh -c`` with the payload on stdin +documented, so it is not used.) These tests run every installed command the way Auggie does. +Shell-compatible command strings are also run through ``sh -c`` with the payload on stdin and as a trailing heredoc, with the emitter installed, with emit.py missing and with python3 -missing. If the whole install folder is deleted, Auggie cannot start the wrapper; 0.36.0 logs -that as a failed hook and continues (none of the registered events can block). +missing. Literal Unicode and parentheses-only paths exercise Auggie's direct-spawn branch, +not an extra shell that Auggie does not use. If the whole install folder is deleted, Auggie +cannot start the wrapper; 0.36.0 logs that as a failed hook and continues (none of the +registered events can block). """ from __future__ import annotations @@ -40,8 +42,10 @@ OBSERVE_EVENTS = ["SessionStart", "Stop", "SessionEnd"] SHELLS = [sh for sh in ("/bin/sh", "/bin/bash", "/bin/zsh", "/bin/dash") if os.path.exists(sh)] WORKSPACE_FILE = ".augment/settings.local.json" -# Home directories that break naive quoting: a space, JSON and sed specials, shell specials. -HOMES = ["home", "my home", "odd &#\"\\$HOME`x`"] +# These names trigger neither Auggie's word splitter nor its shell dispatcher. +DIRECT_SPAWN_HOMES = ["José", "name(test)"] +# Also retain space, JSON/sed-special and shell-metacharacter coverage. +HOMES = ["home", "my home", "odd &#\"\\$HOME`x`", *DIRECT_SPAWN_HOMES] _META = re.compile(r"[|&;><$`]") _WORDS = re.compile(r'"([^"]*(?:\\.[^"]*)*)"|\'([^\']*(?:\\.[^\']*)*)\'|(\S+)') @@ -128,21 +132,28 @@ def test_installed_commands_send_the_payload_and_print_nothing(self): with tempfile.TemporaryDirectory() as tmp: project = Path(tmp, "project") project.mkdir() - for home_name in HOMES: + for home_index, home_name in enumerate(HOMES): home = self.install(tmp, home_name) wrapper = home / ".augment" / "fi-hook-to-otlp" / "futureagi-hook.sh" settings = json.loads((home / ".augment" / "settings.json").read_text()) - runs = [("auggie", "/bin/sh"), ("stdin", "/bin/sh"), ("heredoc", "/bin/sh")] + runs = [("auggie", "/bin/sh")] + if home_name not in DIRECT_SPAWN_HOMES: + runs += [("stdin", "/bin/sh"), ("heredoc", "/bin/sh")] if home_name == "home": runs += [(t, sh) for sh in SHELLS for t in ("stdin", "heredoc")] for transport, shell in runs: label = f"{home_name!r} {transport} {shell}" for _event, hook in commands(settings): argv = auggie_argv(hook["command"]) - self.assertIn(str(wrapper), argv[-1] if argv[0] == "bash" else argv[0], label) + if home_name in DIRECT_SPAWN_HOMES: + self.assertEqual(hook["command"], str(wrapper), label) + if argv[0] == "bash": + self.assertEqual(argv, ["bash", "-c", f"'{wrapper}'"], label) + else: + self.assertEqual(argv, [str(wrapper)], label) rx = Receiver() try: - sid = f"cfg-{len(home_name)}-{transport}-{Path(shell).name}" + sid = f"cfg-{home_index}-{transport}-{Path(shell).name}" env = self.base_env(home, FI_API_KEY="k", FI_SECRET_KEY="s", FI_HOOK_SYNC="1", FI_HOOK_CAPTURE_CONTENT="1", FI_OTLP_ENDPOINT=rx.url + "/tracer/v1/traces", From 567ff7e2d3f72d5a96a2eb04255675accef17549 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 22:34:01 -0800 Subject: [PATCH 7/8] docs(augment): escape backtick for macOS installer parsing 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 --- examples/coding-agents/augment-code/install.sh | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh index 6e066f034..a18577014 100755 --- a/examples/coding-agents/augment-code/install.sh +++ b/examples/coding-agents/augment-code/install.sh @@ -69,7 +69,8 @@ import json, re, sys template, wrapper = sys.argv[1], sys.argv[2] if "'" in wrapper: sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") -if re.search(r"[ |&;><$`]", wrapper): +# Escape the backtick for macOS Bash 3.2's command-substitution heredoc parser. +if re.search(r"[ |&;><$\x60]", wrapper): wrapper = f"'{wrapper}'" with open(template, encoding="utf-8") as f: settings = json.load(f) From 72cd2bb1bb48166bdab3305ee41868b1545bc31b Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Thu, 5 Nov 2026 22:35:58 -0800 Subject: [PATCH 8/8] docs(augment): render settings outside nested shell substitution 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 --- examples/coding-agents/augment-code/install.sh | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/examples/coding-agents/augment-code/install.sh b/examples/coding-agents/augment-code/install.sh index a18577014..4bfa1337f 100755 --- a/examples/coding-agents/augment-code/install.sh +++ b/examples/coding-agents/augment-code/install.sh @@ -63,14 +63,15 @@ ignore_workspace_settings() { # Unicode and parentheses) go straight to spawn: quotes would become part of # the filename instead of being removed. # Built before anything is copied, so a path that cannot be registered leaves -# no partial install behind. -HOOKS="$(python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' +# no partial install behind. Keep the heredoc outside command substitution: +# macOS Bash 3.2 can misparse quotes and backticks inside a nested heredoc. +render_hooks() { + python3 - "$HERE/settings.json" "$DEST/futureagi-hook.sh" <<'PY' import json, re, sys template, wrapper = sys.argv[1], sys.argv[2] if "'" in wrapper: sys.exit(f"cannot register a hook path that contains a single quote: {wrapper}") -# Escape the backtick for macOS Bash 3.2's command-substitution heredoc parser. -if re.search(r"[ |&;><$\x60]", wrapper): +if re.search(r"[ |&;><$`]", wrapper): wrapper = f"'{wrapper}'" with open(template, encoding="utf-8") as f: settings = json.load(f) @@ -80,7 +81,8 @@ for groups in settings["hooks"].values(): hook["command"] = wrapper print(json.dumps(settings, indent=2)) PY -)" +} +HOOKS="$(render_hooks)" mkdir -p "$DEST/adapters" cp "$EMITTER/emit.py" "$DEST/emit.py"