Repository navigation
docs(afk): refresh README against agent-afk 5.286.1 source - #35
Merged
Merged
Conversation
Update adapters/afk/README.md for seven verified changes in agent-afk: 1. Blocking additionalContext on PreToolUse now reaches the model (dispatcher.pre-dispatch-gates.ts:548; v5.121.0). Non-blocking additionalContext is still dropped (#2778). 2. transcript_path is sent in hook stdin payloads from v5.276.14 (command-executor.ts:101-104, 156-162). Null on daemon/chat/web/ pre-first-turn REPL. 3. PreCompact hook event fires before manual and auto-compact (config- loader.ts:286; v5.10.0). Can block compaction; cannot select blocks. 4. PreToolUse hooks fire inside subagent forks (fork-child-config.ts:314; v5.121.0). SessionStart injectContext is gated on parentSessionId=== undefined so it does not reach forks (provider-lifecycle.ts:171). 5. pluginHookEnv (command-executor.ts:347-383; v5.276.21, #2700) is the supported route for TYPESAFE_API_KEY / OPENROUTER_API_KEY. Key matches manifest name "claude-jev-afk". process.env wins over afk.env. Direct afk.env read is documented as fallback. 6. UserPromptSubmit and Stop dispatch sites confirmed (loop-iteration.ts: 559, 795). Added #2817 link. Added #2816 (per-hook disable) to subagent gap. 7. CLAUDE_PLUGIN_OPTION_* and CLAUDE_CONFIG_DIR now exported by v5.286.1 (command-executor.ts:492+; #2373 closed). Adapter has no userConfig fields so receives no CLAUDE_PLUGIN_OPTION_* today. Also: updated "How blocking works" to reflect blocking additionalContext behavior; updated Runtime requirements key-storage line. CHANGELOG [Unreleased] bullet added.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="adapters/afk/README.md">
<violation number="1" location="adapters/afk/README.md:64">
P2: This sentence is false once `pluginHookEnv` is configured: AFK forwards a key inherited in its `process.env` to the hook. Qualify it to describe only the reduced environment without `pluginHookEnv`.</violation>
<violation number="2" location="adapters/afk/README.md:146">
P3: The bullet is still titled "No transcript access", but its own first sentence now says AFK sends `transcript_path` in hook stdin (agent-afk 5.276.14) and that it is available in the REPL after the first turn — which is exactly where the prompt router and Stop sweep run. Retitle the bullet to reflect the remaining gap (null on daemon/chat/web, unused by the adapter), e.g. "Transcript access is limited".</violation>
</file>
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
| `TYPESAFE_API_KEY` is checked first. The SessionStart hook (rule digest) requires no API key. | ||
|
|
||
| AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. A key exported in your shell does not reach the hooks. Store it in AFK's env file instead, which the hooks read when AFK runs them. `afk config env set` refuses these names (`unknown config key`, agent-afk 5.259.0), so add the line with an editor: | ||
| AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. A key exported in your shell does not reach the hooks. |
There was a problem hiding this comment.
P2: This sentence is false once pluginHookEnv is configured: AFK forwards a key inherited in its process.env to the hook. Qualify it to describe only the reduced environment without pluginHookEnv.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At adapters/afk/README.md, line 64:
<comment>This sentence is false once `pluginHookEnv` is configured: AFK forwards a key inherited in its `process.env` to the hook. Qualify it to describe only the reduced environment without `pluginHookEnv`.</comment>
<file context>
@@ -61,7 +61,22 @@ export OPENROUTER_API_KEY=sk-or-...
`TYPESAFE_API_KEY` is checked first. The SessionStart hook (rule digest) requires no API key.
-AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. A key exported in your shell does not reach the hooks. Store it in AFK's env file instead, which the hooks read when AFK runs them. `afk config env set` refuses these names (`unknown config key`, agent-afk 5.259.0), so add the line with an editor:
+AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. A key exported in your shell does not reach the hooks.
+
+**Supported route (agent-afk 5.276.21):** add the key to `pluginHookEnv` in `~/.afk/config/afk.config.json`, keyed by the plugin's manifest name (`claude-jev-afk`):
</file context>
Suggested change
| AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. A key exported in your shell does not reach the hooks. | |
| AFK starts hook commands with a reduced environment: `PATH`, `HOME`, `SHELL`, `LANG`, `TERM`, `TMPDIR`, `USER`, `LOGNAME`, non-secret `AFK_*` variables, and `CLAUDE_PLUGIN_ROOT`. Without `pluginHookEnv`, a key exported in your shell does not reach the hooks. |
| - **Named agents are not routed**: a spawn with an `agent_type` takes that agent's model defaults, so the hook skips the tier question and only checks the brief. | ||
| - **No transcript access**: Hooks receive only the current event, not the conversation. The prompt router uses the prompt alone (the Python adapter also uses the previous turn). | ||
| - **No compaction hook**: AFK CLI hooks do not expose the transcript access needed for Jev-scored compaction. | ||
| - **No transcript access**: AFK sends `transcript_path` in hook stdin payloads from agent-afk 5.276.14 ([griffinwork40/agent-afk#2647](https://github.com/griffinwork40/agent-afk/pull/2647)). It is `null` on daemon, `afk chat`, and web surfaces, and in the REPL before the first turn completes. The adapter does not use it yet (the prompt router uses the prompt alone; the Python adapter also uses the previous turn). |
There was a problem hiding this comment.
P3: The bullet is still titled "No transcript access", but its own first sentence now says AFK sends transcript_path in hook stdin (agent-afk 5.276.14) and that it is available in the REPL after the first turn — which is exactly where the prompt router and Stop sweep run. Retitle the bullet to reflect the remaining gap (null on daemon/chat/web, unused by the adapter), e.g. "Transcript access is limited".
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At adapters/afk/README.md, line 146:
<comment>The bullet is still titled "No transcript access", but its own first sentence now says AFK sends `transcript_path` in hook stdin (agent-afk 5.276.14) and that it is available in the REPL after the first turn — which is exactly where the prompt router and Stop sweep run. Retitle the bullet to reflect the remaining gap (null on daemon/chat/web, unused by the adapter), e.g. "Transcript access is limited".</comment>
<file context>
@@ -119,15 +136,16 @@ The `AFK rule checks` section of `stats.py` counts these per phase, lists the ru
- **Named agents are not routed**: a spawn with an `agent_type` takes that agent's model defaults, so the hook skips the tier question and only checks the brief.
-- **No transcript access**: Hooks receive only the current event, not the conversation. The prompt router uses the prompt alone (the Python adapter also uses the previous turn).
-- **No compaction hook**: AFK CLI hooks do not expose the transcript access needed for Jev-scored compaction.
+- **No transcript access**: AFK sends `transcript_path` in hook stdin payloads from agent-afk 5.276.14 ([griffinwork40/agent-afk#2647](https://github.com/griffinwork40/agent-afk/pull/2647)). It is `null` on daemon, `afk chat`, and web surfaces, and in the REPL before the first turn completes. The adapter does not use it yet (the prompt router uses the prompt alone; the Python adapter also uses the previous turn).
+- **PreCompact hook exists but cannot select what to keep**: A `PreCompact` hook event fires before any compaction (manual `/compact` or auto-compact). It can block compaction entirely (agent-afk 5.10.0 for manual, 5.10.0 for auto). It cannot choose which conversation blocks to keep; that requires transcript-level access the hook does not receive. The adapter does not register a `PreCompact` handler today.
+- **SessionStart injectContext reaches the parent session only**: AFK gates SessionStart `injectContext` delivery on `parentSessionId === undefined` (`provider-lifecycle.ts`), so the rule digest injected by `session-start.ts` does not reach subagent forks. `PreToolUse` hooks (rules) do fire inside forks.
</file context>
Suggested change
| - **No transcript access**: AFK sends `transcript_path` in hook stdin payloads from agent-afk 5.276.14 ([griffinwork40/agent-afk#2647](https://github.com/griffinwork40/agent-afk/pull/2647)). It is `null` on daemon, `afk chat`, and web surfaces, and in the REPL before the first turn completes. The adapter does not use it yet (the prompt router uses the prompt alone; the Python adapter also uses the previous turn). | |
| - **Transcript access is limited**: AFK sends `transcript_path` in hook stdin payloads from agent-afk 5.276.14 ([griffinwork40/agent-afk#2647](https://github.com/griffinwork40/agent-afk/pull/2647)). It is `null` on daemon, `afk chat`, and web surfaces, and in the REPL before the first turn completes. The adapter does not use it yet (the prompt router uses the prompt alone; the Python adapter also uses the previous turn). |
The previous commit said agent-afk 5.286.1 closed #2373. It did not: #2373 is open and its implementation (agent-afk PR #2732, commit 4819e9eb1) is unmerged and in no release tag. Restore the gap, cite 5.286.1, and link the pending PR.
There was a problem hiding this comment.
1 issue found across 2 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="adapters/afk/README.md">
<violation number="1" location="adapters/afk/README.md:139">
P3: The provider is not inherently unpinnable: the adapter honors `CLAUDE_PLUGIN_OPTION_PROVIDER`, and `pluginHookEnv` is documented as forwarding explicitly listed variables. Qualify this as unavailable in AFK’s default environment rather than saying it cannot be pinned.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Fix all with cubic | Re-trigger cubic
| - **Subagent routing is not delivered**: AFK command hooks read only `continue`, `decision`, `reason`, and `hookSpecificOutput.additionalContext` (agent-afk 5.265.3, [#2371](https://github.com/griffinwork40/agent-afk/issues/2371)), and AFK keeps nothing but a block from a `PreToolUse` hook (agent-afk 5.259.0). The subagent router never blocks, so its tier recommendation and missing-brief note reach neither the agent nor the user, and the hook cannot switch the model. AFK does honor `decision: "block"` with a `reason`, so denying a bad brief is possible, but the adapter does not do it yet. | ||
| - **Uncertain rule matches are not delivered**: see [How blocking works](#how-blocking-works). | ||
| - **Prompt and turn-end hooks run only in the REPL**: AFK fires `UserPromptSubmit` and `Stop` only in the interactive REPL, so the prompt router and the Stop sweep never run in `afk chat`, Telegram, or daemon sessions. | ||
| - **Hook environment**: AFK passes neither `CLAUDE_CONFIG_DIR` nor `CLAUDE_PLUGIN_OPTION_*` to hooks (agent-afk 5.286.1, [#2373](https://github.com/griffinwork40/agent-afk/issues/2373), open; [#2732](https://github.com/griffinwork40/agent-afk/pull/2732) proposes exporting both). Logs go to `~/.claude`, and the provider follows the key's prefix; it cannot be pinned. Use `pluginHookEnv` for the API key (see Setup). |
There was a problem hiding this comment.
P3: The provider is not inherently unpinnable: the adapter honors CLAUDE_PLUGIN_OPTION_PROVIDER, and pluginHookEnv is documented as forwarding explicitly listed variables. Qualify this as unavailable in AFK’s default environment rather than saying it cannot be pinned.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At adapters/afk/README.md, line 139:
<comment>The provider is not inherently unpinnable: the adapter honors `CLAUDE_PLUGIN_OPTION_PROVIDER`, and `pluginHookEnv` is documented as forwarding explicitly listed variables. Qualify this as unavailable in AFK’s default environment rather than saying it cannot be pinned.</comment>
<file context>
@@ -136,7 +136,7 @@ The `AFK rule checks` section of `stats.py` counts these per phase, lists the ru
## Known gaps
-- **Hook environment**: AFK passes `CLAUDE_CONFIG_DIR` to hooks as of agent-afk 5.286.1 ([griffinwork40/agent-afk#2373](https://github.com/griffinwork40/agent-afk/issues/2373) closed). `CLAUDE_PLUGIN_OPTION_*` is now exported for declared non-sensitive `userConfig` fields (agent-afk 5.286.1). The adapter does not declare `userConfig` fields, so it receives no `CLAUDE_PLUGIN_OPTION_*` today; use `pluginHookEnv` for secrets (see Setup).
+- **Hook environment**: AFK passes neither `CLAUDE_CONFIG_DIR` nor `CLAUDE_PLUGIN_OPTION_*` to hooks (agent-afk 5.286.1, [#2373](https://github.com/griffinwork40/agent-afk/issues/2373), open; [#2732](https://github.com/griffinwork40/agent-afk/pull/2732) proposes exporting both). Logs go to `~/.claude`, and the provider follows the key's prefix; it cannot be pinned. Use `pluginHookEnv` for the API key (see Setup).
- **Key from `afk.env`**: `pluginHookEnv` (agent-afk 5.276.21) is the supported route to forward `TYPESAFE_API_KEY` and `OPENROUTER_API_KEY` to hook subprocesses. The adapter's direct `afk.env` read is a fallback the hooks still perform.
- **Subagent routing is not delivered**: The subagent router never blocks, so its tier recommendation and missing-brief note reach neither the agent nor the user. `PreToolUse` hooks fire inside subagent child sessions (agent-afk 5.121.0, `fork-child-config.ts`), so the rule hook already judges edits made by subagents. A single plugin hook cannot be disabled without editing `hooks.json` ([griffinwork40/agent-afk#2816](https://github.com/griffinwork40/agent-afk/issues/2816)).
</file context>
Suggested change
| - **Hook environment**: AFK passes neither `CLAUDE_CONFIG_DIR` nor `CLAUDE_PLUGIN_OPTION_*` to hooks (agent-afk 5.286.1, [#2373](https://github.com/griffinwork40/agent-afk/issues/2373), open; [#2732](https://github.com/griffinwork40/agent-afk/pull/2732) proposes exporting both). Logs go to `~/.claude`, and the provider follows the key's prefix; it cannot be pinned. Use `pluginHookEnv` for the API key (see Setup). | |
| - **Hook environment**: AFK does not automatically pass `CLAUDE_CONFIG_DIR` or `CLAUDE_PLUGIN_OPTION_*` to hooks (agent-afk 5.286.1, [#2373](https://github.com/griffinwork40/agent-afk/issues/2373), open; [#2732](https://github.com/griffinwork40/agent-afk/pull/2732) proposes exporting both). Logs go to `~/.claude`; the default provider follows the key's prefix, while the adapter still honors `CLAUDE_PLUGIN_OPTION_PROVIDER` when it is explicitly supplied. Use `pluginHookEnv` for the API key (see Setup). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refreshes
adapters/afk/README.mdagainst agent-afk 5.286.1 source. All claims verified withgit log -S,git tag --contains, and direct source reads. Thepatch_applyKnown-gaps bullet and therules.tshook-table row are untouched (owned by sibling branches).Per-claim table
additionalContextis appended to the error tool result the model sees; non-blocking is still dropped (#2778)dispatcher.pre-dispatch-gates.ts:548(err.injectContextappended toblockResult.content)b423000ac)command-executor.ts:101-104,156-16239e88574a)config-loader.ts:286;query-turn-driver.auto-compact.ts:53-61;cli/slash/commands/core.ts:85-91aa25b101,eba1ef9c)parentSessionId === undefinedfork-child-config.ts:314;provider-lifecycle.ts:171pluginHookEnvdocumented as supported route (key =claude-jev-afk); process.env wins over afk.env; afk.env read is documented as fallbackcommand-executor.ts:347-383(applyPluginHookEnv);config-loader.ts:241-2634c3db5ee4)loop-iteration.ts:559(UserPromptSubmit),:795(Stop)command-executor.tsenv allowlist (noCLAUDE_CONFIG_DIR);4819e9eb1is only on PR #2732 branchesAdditional fixes beyond the list
claude-jev-afk(verified from.claude-plugin/plugin.json), precedence note, and security constraint (user-global only). Restructured existing afk.env text as "Fallback".CHANGELOG
[Unreleased] bullet added summarizing all seven items.
Not done / open questions
None. The
patch_applybullet and rules.ts hook-table row were not touched per instructions (owned by sibling branches).Summary by cubic
Refreshes
adapters/afk/README.mdand the CHANGELOG against agent-afk 5.286.1 source, correcting seven out-of-date claims verified against tags and source reads. Thepatch_applygap bullet andrules.tstable row are intentionally untouched.Highlights:
additionalContextonPreToolUsenow reaches the model; non-blocking is still dropped (#2778).transcript_pathin hook stdin, thePreCompacthook event, andPreToolUsefiring in subagent forks (whereSessionStartinjectContext does not).pluginHookEnvas the supported route forTYPESAFE_API_KEY/OPENROUTER_API_KEY, with directafk.envread as fallback.CLAUDE_CONFIG_DIR/CLAUDE_PLUGIN_OPTION_*gap as still unfixed on 5.286.1: #2373 is open and the implementation in PR #2732 is unmerged; also adds #2816/#2817 links.pluginHookEnvsetup example, and updates Runtime requirements to match.Written for commit 65a624d. Summary will update on new commits.