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.
- manifest.yaml: no plugin-include change (this is not a plugin).
- 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]}"
+        )

plugins/git/.claude-plugin/plugin.json

@@ -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

plugins/git/README.md

@@ -36,7 +36,6 @@ plugins:
     - sdlc
     - workspace
     - observability
-    - git
   # Install location in the image
   install_path: /opt/agentic/plugins
 

providers/workspaces/claude-cli/Dockerfile

@@ -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.
@@ -107,28 +109,31 @@ fi
 # EVERY repo cloned or initialized inside this container — including repos
 # cloned by the agent mid-task.
 #
-# Multiple plugins can contribute git hooks. We compose them into a single
-# runtime directory ($GIT_HOOKS_DIR) and point core.hooksPath at it:
-#   - observability/hooks/git/  → event-emission (post-commit, pre-push, …)
-#   - git/hooks/                → other git concerns (prepare-commit-msg, …)
+# 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.
 #
-# Each plugin owns hook filenames it ships; collisions across plugins are not
-# expected today. If two plugins ever ship the same hook name, the second
-# symlink wins.
-#
-# Observability hooks emit JSONL 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.
+# 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}"
 
-PLUGINS_BASE="${AGENTIC_PLUGINS_DIR:-/opt/agentic/plugins}"
-for src_dir in "${PLUGINS_BASE}/observability/hooks/git" "${PLUGINS_BASE}/git/hooks"; do
+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}")
-        # Skip non-hook files (installer, docs)
         case "${name}" in install.py|*.md|*.txt) continue ;; esac
         ln -sf "${src}" "${GIT_HOOKS_DIR}/${name}"
     done

providers/workspaces/claude-cli/manifest.yaml

@@ -1,31 +1,29 @@
 #!/bin/sh
 # prepare-commit-msg — append operator Co-authored-by trailer.
-# Plugin marker for install.py uninstall detection: agentic_events
 #
 # 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/commit)
-#     so we don't pollute them.
+#   - 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"
 
-# Skip auto-generated message sources so we don't pollute them.
-#   merge    — message produced by `git merge`
-#   squash   — message produced by `git merge --squash`
-#   template — user has a commit.template configured
-#   commit   — reusing an existing commit (e.g. `git commit --amend`,
-#              `git cherry-pick`). The original message already has any
-#              trailer it should have; idempotency below handles re-adds.
 case "$COMMIT_SOURCE" in
-    merge|squash|template|commit) exit 0 ;;
+    merge|squash|template) exit 0 ;;
 esac
 
 if [ -z "$SYN_OPERATOR_NAME" ] || [ -z "$SYN_OPERATOR_EMAIL" ]; then