feat(workspace): operator Co-authored-by trailer (#158)

Workspace-shipped prepare-commit-msg hook for operator attribution.
NOT a Claude Code plugin — the hook lives with the claude-cli provider
itself, gets baked into the image, and is installed by the entrypoint.

When SYN_OPERATOR_NAME and SYN_OPERATOR_EMAIL are both set, every
workspace commit gets a 'Co-authored-by: NAME <EMAIL>' trailer so PRs
the agent opens are attributed to the operator who sponsored the
workspace. No-op when either env var is unset (backward compatible).

Layout:
  providers/workspaces/claude-cli/
    scripts/
      entrypoint.sh
      git-hooks/
        prepare-commit-msg     <- new

Changes:
- New scripts/git-hooks/prepare-commit-msg. Skips merge/squash/template
  message sources to avoid polluting auto-generated messages. Does NOT
  skip 'commit' source so amend / cherry-pick / rebase still pick up
  the trailer when missing; idempotency check handles re-adds. Strips
  CR/LF from operator inputs (defense in depth).
- Dockerfile: COPY scripts/git-hooks/ -> /opt/agentic/git-hooks/.
- entrypoint.sh: compose hooks from /opt/agentic/git-hooks/ AND
  plugins/observability/hooks/git/ into $HOME/.git-hooks, then point
  core.hooksPath there. Two contributing sources, well-documented.
  Also lists SYN_OPERATOR_* in the env var header.
- scripts/build-provider.py: stage_scripts now copies the entire
  scripts/ tree (was top-level files only) so subdirs like git-hooks/
  reach the build context.
- New tests/integration/test_workspace_operator_attribution.py with
  8 tests covering: no-env / with-env / one-env-only / idempotency /
  template-skip / merge-skip / amend-still-gets-trailer / newline-
  injection-sanitized.

Resolves #158.

Verification (rebuilt 2.1.126 image):
  - 8/8 new operator-attribution tests pass.
  - 27/27 pre-existing integration tests pass.
  - Composed hooks layout in container:
      $HOME/.git-hooks/
        post-checkout      -> plugins/observability/hooks/git/post-checkout
        post-commit        -> plugins/observability/hooks/git/post-commit
        post-merge         -> plugins/observability/hooks/git/post-merge
        post-rewrite       -> plugins/observability/hooks/git/post-rewrite
        pre-push           -> plugins/observability/hooks/git/pre-push
        prepare-commit-msg -> /opt/agentic/git-hooks/prepare-commit-msg
  - Observability git_commit events still emit on stderr.

Author: NeuralEmpowerment

lib/python/agentic_isolation/tests/integration/test_workspace_operator_attribution.py

@@ -0,0 +1,214 @@
+"""Integration tests for the workspace's prepare-commit-msg hook.
+
+The hook lives at:
+    providers/workspaces/claude-cli/scripts/git-hooks/prepare-commit-msg
+
+It is shipped *with the workspace image* (not as a Claude Code plugin).
+The entrypoint composes it into the runtime git hooks directory at
+container startup. When SYN_OPERATOR_NAME and SYN_OPERATOR_EMAIL are
+both set, the hook appends a `Co-authored-by:` trailer to commit messages.
+
+These tests run real git commits inside the rebuilt workspace image and
+assert the hook's behavior end-to-end (entrypoint composition + hook
+script + git plumbing all working together).
+
+Requirements:
+    - Docker available
+    - agentic-workspace-claude-cli:latest built locally
+
+Run with: pytest tests/integration/test_workspace_operator_attribution.py -v
+"""
+
+from __future__ import annotations
+
+import subprocess
+import textwrap
+
+import pytest
+
+WORKSPACE_IMAGE = "agentic-workspace-claude-cli:latest"
+OPERATOR_NAME = "TestOperator"
+OPERATOR_EMAIL = "operator@example.test"
+
+
+def docker_available() -> bool:
+    try:
+        result = subprocess.run(
+            ["docker", "image", "inspect", WORKSPACE_IMAGE],
+            capture_output=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except FileNotFoundError:
+        return False
+
+
+pytestmark = [
+    pytest.mark.integration,
+    pytest.mark.skipif(
+        not docker_available(),
+        reason=f"Docker or {WORKSPACE_IMAGE} not available — run `just build-workspace-claude-cli`",
+    ),
+]
+
+
+def run_in_workspace(script: str, env: dict[str, str] | None = None) -> str:
+    """Run `script` (bash) inside a fresh workspace container, return stdout.
+
+    The default entrypoint runs first (so git hooks get composed); then
+    `script` runs as the CMD argument. GIT_AUTHOR_* are always set so
+    git commits succeed inside the container.
+    """
+    env = env or {}
+    cmd = [
+        "docker", "run", "--rm",
+        "-e", "GIT_AUTHOR_NAME=workspace-agent",
+        "-e", "GIT_AUTHOR_EMAIL=agent@workspace.test",
+    ]
+    for key, value in env.items():
+        cmd.extend(["-e", f"{key}={value}"])
+    cmd.extend([WORKSPACE_IMAGE, "bash", "-c", script])
+
+    result = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    if result.returncode != 0:
+        pytest.fail(
+            f"Command failed (exit {result.returncode}):\n"
+            f"--- stdout ---\n{result.stdout}\n"
+            f"--- stderr ---\n{result.stderr}"
+        )
+    return result.stdout
+
+
+def commit_and_read_message(extra_setup: str = "", env: dict[str, str] | None = None) -> str:
+    """Init a repo, commit, return the commit message body."""
+    script = textwrap.dedent(f"""
+        set -e
+        cd /tmp && rm -rf repo && git init -q repo && cd repo
+        echo file > file
+        git add file
+        {extra_setup}
+        git commit -q -m "test commit"
+        git log -1 --format=%B
+    """)
+    return run_in_workspace(script, env=env)
+
+
+class TestOperatorAttribution:
+    """End-to-end tests for the prepare-commit-msg hook."""
+
+    def test_no_env_vars_leaves_message_untouched(self) -> None:
+        """Without SYN_OPERATOR_* set, the hook should be a no-op."""
+        msg = commit_and_read_message()
+        assert "Co-authored-by:" not in msg, f"unexpected trailer in:\n{msg}"
+
+    def test_with_operator_env_appends_trailer(self) -> None:
+        """Both env vars set → a single Co-authored-by trailer is appended."""
+        msg = commit_and_read_message(
+            env={"SYN_OPERATOR_NAME": OPERATOR_NAME, "SYN_OPERATOR_EMAIL": OPERATOR_EMAIL},
+        )
+        expected = f"Co-authored-by: {OPERATOR_NAME} <{OPERATOR_EMAIL}>"
+        assert expected in msg, f"missing trailer in:\n{msg}"
+        assert msg.count("Co-authored-by:") == 1
+
+    def test_only_name_set_is_no_op(self) -> None:
+        """Either env var alone → no trailer (both are required)."""
+        msg = commit_and_read_message(env={"SYN_OPERATOR_NAME": OPERATOR_NAME})
+        assert "Co-authored-by:" not in msg
+
+    def test_idempotent_when_trailer_already_present(self) -> None:
+        """If the user's commit message already has the same trailer, don't double-append."""
+        # Use -m with newlines via printf so the trailer is in the message from the start
+        existing = f"Co-authored-by: {OPERATOR_NAME} <{OPERATOR_EMAIL}>"
+        script = textwrap.dedent(f"""
+            set -e
+            cd /tmp && rm -rf repo && git init -q repo && cd repo
+            echo file > file && git add file
+            git commit -q -m "test commit" -m "{existing}"
+            git log -1 --format=%B
+        """)
+        msg = run_in_workspace(
+            script,
+            env={"SYN_OPERATOR_NAME": OPERATOR_NAME, "SYN_OPERATOR_EMAIL": OPERATOR_EMAIL},
+        )
+        assert msg.count("Co-authored-by:") == 1, f"trailer duplicated:\n{msg}"
+
+    def test_template_source_skipped(self) -> None:
+        """Direct hook invocation with COMMIT_SOURCE=template must leave the message unchanged."""
+        script = textwrap.dedent("""
+            set -e
+            HOOK=/opt/agentic/git-hooks/prepare-commit-msg
+            test -x "$HOOK" || { echo "HOOK_MISSING"; exit 1; }
+            echo "from-template" > /tmp/msg
+            "$HOOK" /tmp/msg template
+            cat /tmp/msg
+        """)
+        out = run_in_workspace(
+            script,
+            env={"SYN_OPERATOR_NAME": OPERATOR_NAME, "SYN_OPERATOR_EMAIL": OPERATOR_EMAIL},
+        )
+        assert "Co-authored-by:" not in out, f"trailer should be skipped on template source:\n{out}"
+
+    def test_merge_source_skipped(self) -> None:
+        """Direct hook invocation with COMMIT_SOURCE=merge must leave the message unchanged."""
+        script = textwrap.dedent("""
+            set -e
+            HOOK=/opt/agentic/git-hooks/prepare-commit-msg
+            echo "merge msg" > /tmp/msg
+            "$HOOK" /tmp/msg merge
+            cat /tmp/msg
+        """)
+        out = run_in_workspace(
+            script,
+            env={"SYN_OPERATOR_NAME": OPERATOR_NAME, "SYN_OPERATOR_EMAIL": OPERATOR_EMAIL},
+        )
+        assert "Co-authored-by:" not in out
+
+    def test_amend_commit_does_get_trailer(self) -> None:
+        """`git commit --amend` (COMMIT_SOURCE=commit) should still get the trailer if missing.
+
+        This guards the explicit decision NOT to skip COMMIT_SOURCE=commit.
+        """
+        script = textwrap.dedent("""
+            set -e
+            cd /tmp && rm -rf repo && git init -q repo && cd repo
+            echo file > file && git add file
+            # First commit WITHOUT operator env to produce a trailer-less HEAD
+            unset SYN_OPERATOR_NAME SYN_OPERATOR_EMAIL
+            git commit -q -m "initial"
+            # Now amend WITH operator env — the hook should add the trailer
+            export SYN_OPERATOR_NAME="$NAME" SYN_OPERATOR_EMAIL="$EMAIL"
+            git commit -q --amend --no-edit
+            git log -1 --format=%B
+        """)
+        msg = run_in_workspace(
+            script,
+            env={"NAME": OPERATOR_NAME, "EMAIL": OPERATOR_EMAIL},
+        )
+        assert f"Co-authored-by: {OPERATOR_NAME} <{OPERATOR_EMAIL}>" in msg, (
+            f"amend should pick up trailer when missing:\n{msg}"
+        )
+
+    def test_newline_in_env_var_does_not_inject_extra_trailer(self) -> None:
+        """A newline in SYN_OPERATOR_NAME must not split into two trailer lines."""
+        # Pass a literal newline via $'...' inside the docker -c shell
+        script = textwrap.dedent("""
+            set -e
+            cd /tmp && rm -rf repo && git init -q repo && cd repo
+            echo file > file && git add file
+            export SYN_OPERATOR_NAME=$'evil\\nCo-authored-by: attacker <bad@bad.test>'
+            export SYN_OPERATOR_EMAIL='ne@example.com'
+            git commit -q -m "newline test"
+            git log -1 --format=%B
+        """)
+        msg = run_in_workspace(script)
+        trailer_lines = [line for line in msg.splitlines() if line.startswith("Co-authored-by:")]
+        assert len(trailer_lines) == 1, (
+            f"newline injection should be sanitized to a single trailer line; got {len(trailer_lines)}:\n{msg}"
+        )
+        # The single trailer's email field (last <...> on the line) must be the
+        # operator email, not the attacker's. The attacker substring may still
+        # appear inside the (now malformed) name field — that's cosmetic; the
+        # security goal is that no separate trailer line was injected.
+        assert trailer_lines[0].rstrip().endswith("<ne@example.com>"), (
+            f"trailer's email field should be the operator email, got:\n{trailer_lines[0]}"
+        )

providers/workspaces/claude-cli/Dockerfile

@@ -171,16 +171,21 @@ RUN mkdir -p /workspace/artifacts/input \
 # NOTE: ~/.claude/settings.json is created by entrypoint.sh at runtime
 # because /home/agent is a tmpfs mount that wipes anything baked into the image.
 
-# Copy entrypoint script
+# Copy entrypoint script and workspace-shipped git hooks.
+# git-hooks/ holds non-observability git hooks owned by the workspace itself
+# (e.g. prepare-commit-msg for operator Co-authored-by attribution). These
+# are NOT Claude Code plugins — the entrypoint installs them into the
+# runtime git hooks directory alongside hooks contributed by plugins.
 COPY scripts/entrypoint.sh /opt/agentic/entrypoint.sh
+COPY scripts/git-hooks/ /opt/agentic/git-hooks/
 
 # Copy pre-staged plugins from build context (ADR-033)
 # Each plugin is a self-contained directory with .claude-plugin/plugin.json
 # and hooks/hooks.json using ${CLAUDE_PLUGIN_ROOT} for path resolution.
 COPY plugins/ /opt/agentic/plugins/
 
-# Set permissions on plugins and entrypoint
-RUN chmod -R 755 /opt/agentic/plugins \
+# Set permissions on plugins, entrypoint, and workspace-shipped hooks
+RUN chmod -R 755 /opt/agentic/plugins /opt/agentic/git-hooks \
     && find /opt/agentic/plugins -name "*.py" -exec chmod 755 {} \; \
     && chmod 755 /opt/agentic/entrypoint.sh \
     && chown -R agent:agent /opt/agentic

providers/workspaces/claude-cli/scripts/entrypoint.sh

@@ -18,6 +18,8 @@
 #   GIT_AUTHOR_NAME         - Git commit author name (required for git ops)
 #   GIT_AUTHOR_EMAIL        - Git commit author email (required for git ops)
 #   GITHUB_TOKEN            - GitHub token for git push (optional)
+#   SYN_OPERATOR_NAME       - Operator display name for Co-authored-by trailer (optional)
+#   SYN_OPERATOR_EMAIL      - Operator email matching a verified GitHub account (optional)
 #
 # This script is the SINGLE SOURCE OF TRUTH for workspace configuration.
 # Orchestrators should NOT have hardcoded setup scripts.
@@ -100,23 +102,46 @@ if [ -n "${GIT_AUTHOR_NAME}" ]; then
     git config --global init.defaultBranch main
 fi
 
-# Install observability git hooks globally (ADR-043).
+# Install workspace git hooks globally (ADR-043).
 #
 # core.hooksPath is a git global config that overrides the per-repo .git/hooks/
-# directory. Setting it here (at container startup) means post-commit, pre-push,
-# post-merge, and post-rewrite hooks fire for EVERY repo cloned or initialized
-# inside this container — including repos cloned by the agent mid-task.
+# directory. Setting it here (at container startup) means our hooks fire for
+# EVERY repo cloned or initialized inside this container — including repos
+# cloned by the agent mid-task.
 #
-# The hooks emit JSONL observability events to stderr. The docker exec stream in
-# AgenticEventStreamAdapter uses stderr=STDOUT to capture them alongside Claude's
-# stdout, and WorkflowExecutionEngine stores them in TimescaleDB.
+# Two contributing sources, composed into a single runtime directory:
+#   1. /opt/agentic/git-hooks/                          — workspace-shipped
+#      hooks. Owned by the claude-cli provider itself (this dir is baked in
+#      by the Dockerfile from providers/workspaces/claude-cli/scripts/git-hooks/).
+#      Currently: prepare-commit-msg for operator Co-authored-by attribution
+#      (driven by SYN_OPERATOR_NAME / SYN_OPERATOR_EMAIL env vars; no-op when
+#      either is unset).
+#   2. /opt/agentic/plugins/observability/hooks/git/    — event-emission hooks
+#      from the observability plugin (post-commit, pre-push, post-merge,
+#      post-rewrite, post-checkout). These emit JSONL to stderr; the docker
+#      exec stream in AgenticEventStreamAdapter merges stderr→stdout, and
+#      WorkflowExecutionEngine stores the events in TimescaleDB.
 #
-# Without this line, git hooks only fire in repos that have their own .git/hooks/
-# scripts, which is almost never the case for freshly cloned repos.
-GIT_HOOKS_DIR="${AGENTIC_PLUGINS_DIR:-/opt/agentic/plugins}/observability/hooks/git"
-if [ -d "${GIT_HOOKS_DIR}" ]; then
+# Workspace-shipped hooks are linked first so any future name collision
+# resolves in favor of the observability event emitters (rare, but explicit).
+GIT_HOOKS_DIR="${HOME}/.git-hooks"
+mkdir -p "${GIT_HOOKS_DIR}"
+
+for src_dir in \
+    /opt/agentic/git-hooks \
+    "${AGENTIC_PLUGINS_DIR:-/opt/agentic/plugins}/observability/hooks/git"; do
+    [ -d "${src_dir}" ] || continue
+    for src in "${src_dir}"/*; do
+        [ -f "${src}" ] || continue
+        name=$(basename "${src}")
+        case "${name}" in install.py|*.md|*.txt) continue ;; esac
+        ln -sf "${src}" "${GIT_HOOKS_DIR}/${name}"
+    done
+done
+
+if [ -n "$(ls -A "${GIT_HOOKS_DIR}" 2>/dev/null)" ]; then
     git config --global core.hooksPath "${GIT_HOOKS_DIR}"
-    echo "[entrypoint] Git observability hooks installed from ${GIT_HOOKS_DIR}"
+    echo "[entrypoint] Workspace git hooks composed at ${GIT_HOOKS_DIR}"
 fi
 
 # Also set committer identity (git uses both for commits)

providers/workspaces/claude-cli/scripts/git-hooks/prepare-commit-msg

@@ -0,0 +1,49 @@
+#!/bin/sh
+# prepare-commit-msg — append operator Co-authored-by trailer.
+#
+# When the workspace is run by an operator (e.g. via Syntropic137 selfhost),
+# SYN_OPERATOR_NAME and SYN_OPERATOR_EMAIL identify the human who sponsored
+# the workspace. This hook adds them as a co-author on every agent commit so
+# the operator gets attribution on PRs the workspace opens.
+#
+# This hook is shipped as part of the claude-cli workspace provider (it is
+# NOT a Claude Code plugin). The entrypoint installs it into the runtime
+# git hooks directory at container start.
+#
+# Behavior:
+#   - No-op when either env var is unset (backward compatible).
+#   - Skipped on auto-generated message sources (merge / squash / template)
+#     so we don't pollute them. NOT skipped on `commit` source so
+#     `--amend`, cherry-pick, and rebase commits also get the trailer if
+#     they're missing it; idempotency below handles re-adds.
+#   - Idempotent — won't append if the same trailer already exists.
+#   - Always exits 0 — never blocks a commit on attribution failure.
+
+COMMIT_MSG_FILE="$1"
+COMMIT_SOURCE="$2"
+
+case "$COMMIT_SOURCE" in
+    merge|squash|template) exit 0 ;;
+esac
+
+if [ -z "$SYN_OPERATOR_NAME" ] || [ -z "$SYN_OPERATOR_EMAIL" ]; then
+    exit 0
+fi
+
+# Strip CR/LF from operator inputs — env vars are normally well-formed but we
+# don't want a stray newline in either to inject additional trailers.
+NAME=$(printf '%s' "$SYN_OPERATOR_NAME" | tr -d '\r\n')
+EMAIL=$(printf '%s' "$SYN_OPERATOR_EMAIL" | tr -d '\r\n')
+
+if [ -z "$NAME" ] || [ -z "$EMAIL" ]; then
+    exit 0
+fi
+
+TRAILER="Co-authored-by: ${NAME} <${EMAIL}>"
+
+if grep -qF "$TRAILER" "$COMMIT_MSG_FILE" 2>/dev/null; then
+    exit 0
+fi
+
+printf '\n%s\n' "$TRAILER" >> "$COMMIT_MSG_FILE"
+exit 0

scripts/build-provider.py

@@ -95,18 +95,23 @@ def stage_plugins(manifest: dict, build_context: Path) -> None:
 
 
 def stage_scripts(provider: str, build_context: Path) -> None:
-    """Copy scripts directory (e.g., entrypoint.sh) to build context."""
+    """Copy scripts directory (e.g., entrypoint.sh, git-hooks/) to build context.
+
+    Copies the entire scripts/ tree so subdirectories like git-hooks/ are
+    available to the Dockerfile via `COPY scripts/git-hooks/ ...`.
+    """
     scripts_src = PROVIDERS_DIR / provider / "scripts"
     if not scripts_src.exists():
         return  # No scripts directory
 
     scripts_dst = build_context / "scripts"
-    scripts_dst.mkdir(parents=True, exist_ok=True)
+    if scripts_dst.exists():
+        shutil.rmtree(scripts_dst)
+    shutil.copytree(scripts_src, scripts_dst)
 
-    for script in scripts_src.iterdir():
-        if script.is_file():
-            shutil.copy2(script, scripts_dst / script.name)
-            print(f"  ✓ Script: {script.name}")
+    for path in sorted(scripts_dst.rglob("*")):
+        if path.is_file():
+            print(f"  ✓ Script: {path.relative_to(scripts_dst)}")
 
 
 def build_wheels(build_context: Path) -> None: