Skip to content

fix: cap hook directory walk depth and file count - #23

Closed
SebTardif wants to merge 3 commits into
openclaw:mainfrom
SebTardif:fix/f005-hook-walk-cap
Closed

SebTardif wants to merge 3 commits into
openclaw:mainfrom
SebTardif:fix/f005-hook-walk-cap

Conversation

@SebTardif

Copy link
Copy Markdown
Contributor

What Problem This Solves

babelfish list, babelfish install, and every imported hook run walk the plugin hook directory with no file or depth limit. A plugin can point hooks at a tree with thousands of JSON files or a very deep directory chain. Each walk re-reads that tree from disk.

This PR stops the walk after 50 hook JSON files or 8 nested directories and fails closed, the same way a hook symlink already fails.

Evidence

Public path: babelfish list codex against an installed Codex plugin whose manifest sets hooks to a directory. The compiled CLI at dist/bin.js is the same entrypoint as babelfish list.

Before the cap, inspectBundlePlugin loaded all 51 SessionStart hooks from a 51-file tree and loaded the SessionEnd hook from a 9-level tree. After the cap:

$ node /tmp/proof-babelfish-f005.mjs
51 files exit=1 stderr=Plugin hook tree exceeded the 50-file limit
50 files exit=0 plugins=1 hookCount=50
depth 9 exit=1 stderr=Plugin hook tree exceeded the 8-directory depth limit
depth 8 exit=0 plugins=1 hookCount=1

The compiled walker in dist/bundle-plugins.js contains the same 50-file and 8-depth checks. README and docs/compatibility.md document the limits.

Real behavior proof

  • Behavior or issue addressed: Hook directory discovery no longer walks an unbounded plugin tree. babelfish list rejects a 51-file hook directory and a 9-level hook directory, while 50 files and 8 nested directories still list.

  • Real environment tested: macOS 26.6.2 (Darwin 25.6.0, arm64), Node v26.7.0, compiled @openclaw/babelfish at /tmp/oc-pr-babelfish-F005 after a local build, OPENCLAW_BABELFISH_ROOT pointed at temp Codex plugin installs.

  • Exact steps or command run after this patch: Built the branch, then ran node /tmp/proof-babelfish-f005.mjs. That script writes four temp Codex plugins (51 files, 50 files, depth 9, depth 8) and runs node dist/bin.js list codex for each.

  • Evidence after fix: terminal output from the patched build:

    $ node /tmp/proof-babelfish-f005.mjs
    51 files exit=1 stderr=Plugin hook tree exceeded the 50-file limit
    50 files exit=0 plugins=1 hookCount=50
    depth 9 exit=1 stderr=Plugin hook tree exceeded the 8-directory depth limit
    depth 8 exit=0 plugins=1 hookCount=1
  • Observed result after fix: The 51-file tree and the 9-level tree exit 1 with the cap errors. The 50-file tree lists one plugin with 50 hooks. The 8-level tree lists one plugin with 1 hook.

  • What was not tested: babelfish install from a remote Git URL whose hook tree exceeds the cap. Inspect after install uses the same inspectBundlePlugin walk as list.

Summary

  • What changed: declared hook directories now fail when they contain more than 50 JSON files or nest more than 8 directories.
  • Why: babelfish list, install inspect, and hook invoke re-walk that tree with no bound.
  • Related work: same resource-bound class as #10 (hook output), #16 (clone timeout), #17 (tools/list page cap), and #22 (running-task cap). This PR does not restack those branches.

The missing walk cap has been present since Codex hook directory support in 9fb2d8d (2026-07-01), 59 days on main.

Compatibility

  • Source app(s): Codex and Claude Code (declared or conventional hook directories)
  • Affected surface(s): hook discovery during babelfish list, install inspect, and hook invoke
  • Trust-boundary or execution impact: fail-closed on an oversized hook tree. A single hook JSON file path is unchanged. Existing nested fixtures (one extra directory) stay valid.

Verification

  • Added or updated focused tests.
  • Ran npm run check.
  • Ran npm run pack:check.
  • Updated the README compatibility table when behavior changed.
  • Updated CHANGELOG.md for user-visible or operational changes.
  • Removed secrets, private paths, and generated artifacts from the diff.

Stop unbounded hook directory walks during list, install inspect, and
hook invoke. Reject more than 50 hook JSON files or 8 nested directories.

- Cap hookFiles walk (50 JSON files, depth 8)
- Cover over-cap and at-cap trees in bundle-plugins tests
- Document the limits in README, compatibility, and changelog

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
@clawsweeper

clawsweeper Bot commented Aug 29, 2026 •

Copy link
Copy Markdown

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@clawsweeper clawsweeper Bot added merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Aug 29, 2026
@clawsweeper

clawsweeper Bot commented Aug 29, 2026 •

Copy link
Copy Markdown

Codex review: blocked before merge. Reviewed September 24, 2026, 9:04 AM ET / 13:04 UTC (Revision 12).

ClawSweeper review

What this changes

Babelfish now streams declared Claude Code and Codex hook directories, rejecting trees with more than 50 unique JSON files or eight nested directories, with boundary tests and compatibility documentation.

Merge readiness

⛔ Blocked before merge - 6 items remain

The resource cap addresses an unbounded hook scan and has credible CLI proof, but the unchanged PR head still makes existing oversized plugins fail during inspection. That failure reaches listing, regeneration, and hook invocation. The strict default needs an approved upgrade contract, and GitHub currently reports merge conflicts.

Priority: P2
Reviewed head: 22a241dc4ce08d6db40cda5bdbc9206023d14c82
Owner decision: Required. See Decision needed.

Review scores

Measure Result What it means
Overall readiness 🦐 gold shrimp (3/6) The changed CLI behavior has concrete terminal proof, while the unresolved upgrade contract and hook-wide failure path limit merge readiness.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The captured terminal trace exercises the patched compiled babelfish list codex entrypoint with temporary installed plugins: over-limit trees fail and boundary trees list successfully. It does not establish upgrade or mixed-plugin safety; no stored-data contract changes.
Patch quality 🦐 gold shrimp (3/6) Security review found an item that needs attention.

Verification

Check Result Evidence
Real behavior Verified Sufficient (terminal): The captured terminal trace exercises the patched compiled babelfish list codex entrypoint with temporary installed plugins: over-limit trees fail and boundary trees list successfully. It does not establish upgrade or mixed-plugin safety; no stored-data contract changes.
Evidence reviewed 9 items Introduced limit: The pinned PR adds the shared 50-file budget and throws when a directory exceeds it.
Error propagation: Inspection awaits hook discovery; listing awaits every plugin's inspection; hook invocation awaits the whole listing before running a hook.
Regeneration impact: Native-tool regeneration awaits the same plugin listing, so an already installed oversized plugin can prevent regeneration.
Findings 1 actionable finding [P1] Preserve existing hook trees until the strict limit has an upgrade path
Security Needs attention Decision hooks can be suppressed by an oversized plugin: Hook invocation awaits complete plugin discovery before evaluating any imported hook. The new discovery error can therefore prevent a PreToolUse policy hook in another plugin from returning its decision; the final tool outcome needs explicit mixed-plugin verification.

How this fits together

Babelfish reads installed source-plugin manifests and hook files to build OpenClaw plugin listings and generated tools. It also reads those files before running imported hooks for OpenClaw events.

flowchart LR
  A[Installed plugin manifest] --> B[Declared hook paths]
  B --> C[Hook directory walk]
  C --> D{Within file and depth limits?}
  D -->|Yes| E[Imported hook definitions]
  D -->|No| F[Inspection error]
  E --> G[Listing, generated tools, and hook runs]
Loading

Decision needed

Question Recommendation
Should existing oversized hook trees continue to work by default, with strict limits enabled explicitly, or should this release reject them during every inspection? Preserve existing installs: Keep current behavior as the default and add an explicit strict limit with focused upgrade and mixed-plugin coverage.

Why: The cap is useful, but its unconditional rejection changes installed-plugin behavior and can affect other plugins; the contributor has explicitly left that product choice open.

Before merge

  • Preserve existing hook trees until the strict limit has an upgrade path (P1) - The new throw rejects an installed plugin with 51 valid JSON files or a ninth nested directory. Inspection errors propagate through the complete plugin listing, so one such plugin can stop regeneration and prevent unrelated imported hooks from running. Preserve existing behavior by default or implement the maintainer-approved transition, with existing-installation and mixed-plugin coverage.
  • Resolve security concern: Decision hooks can be suppressed by an oversized plugin - Hook invocation awaits complete plugin discovery before evaluating any imported hook. The new discovery error can therefore prevent a PreToolUse policy hook in another plugin from returning its decision; the final tool outcome needs explicit mixed-plugin verification.
  • Resolve merge risk (P1) - An existing plugin with more than 50 valid hook files or nine nested directories now fails inspection by default. One such plugin can stop listing and regeneration and prevent unrelated imported hooks from being evaluated; no approved upgrade transition or mixed-plugin proof is present.
  • Resolve merge risk (P1) - The current PR head has merge conflicts, so the final merged behavior and validation result are not yet available.
  • Complete next step (P2) - Decide the oversized-tree upgrade contract, implement and validate it across fresh and existing mixed-plugin installs, then resolve merge conflicts and rerun repository checks.
  • Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

  • [P1] Preserve existing hook trees until the strict limit has an upgrade path — src/bundle-plugins.ts:366-367
  • [medium] Decision hooks can be suppressed by an oversized plugin — src/bundle-plugins.ts:366
Agent review details

Security

Needs attention: The cap adds no dependency or execution source, but an oversized plugin can prevent imported decision hooks from being evaluated.

Review metrics

Metric Value Why it matters
Production and test delta production +45/-17 lines; tests +192 lines The added tests cover limit boundaries, but do not cover existing oversized installations or mixed-plugin fallout.

Merge-risk options

Maintainer options:

  1. Preserve existing installs (recommended)
    Make strict rejection opt-in, then cover fresh installs, existing oversized trees, and mixed-plugin behavior before merge.
  2. Own the strict transition
    If the maintainer approves rejection by default, document recovery and prove that decision hooks and unrelated plugins behave safely when one tree exceeds the cap.

Technical review

Best possible solution:

Agree on an upgrade contract that bounds hostile walks while preserving existing installations by default, then prove fresh installs, oversized upgrades, and mixed-plugin hook behavior after resolving conflicts.

Do we have a high-confidence way to reproduce the issue?

Yes. The captured compiled-CLI trace shows the boundary cases after the patch, and source inspection shows the uncapped current-main walk and the new rejection path; the reviewer did not execute code.

Is this the best way to solve the issue?

No. Streaming and a bounded scan address the resource concern, but unconditional rejection is not yet an approved upgrade-safe default.

Full review comments:

  • [P1] Preserve existing hook trees until the strict limit has an upgrade path — src/bundle-plugins.ts:366-367
    The new throw rejects an installed plugin with 51 valid JSON files or a ninth nested directory. Inspection errors propagate through the complete plugin listing, so one such plugin can stop regeneration and prevent unrelated imported hooks from running. Preserve existing behavior by default or implement the maintainer-approved transition, with existing-installation and mixed-plugin coverage.
    Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.93

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 1a81d46cc5d3.

Labels

Label changes:

No label changes.

Label justifications:

  • P2: This is a bounded resource-safety improvement with a material but limited compatibility decision before merge.
  • merge-risk: 🚨 compatibility: The new default rejects plugin trees that the current release accepts.
  • merge-risk: 🚨 security-boundary: An oversized plugin can prevent imported decision hooks from being evaluated before a tool call.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
  • status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (terminal): The captured terminal trace exercises the patched compiled babelfish list codex entrypoint with temporary installed plugins: over-limit trees fail and boundary trees list successfully. It does not establish upgrade or mixed-plugin safety; no stored-data contract changes.
  • proof: sufficient: Contributor real behavior proof is sufficient. The captured terminal trace exercises the patched compiled babelfish list codex entrypoint with temporary installed plugins: over-limit trees fail and boundary trees list successfully. It does not establish upgrade or mixed-plugin safety; no stored-data contract changes.

Evidence

Security concerns:

  • [medium] Decision hooks can be suppressed by an oversized plugin — src/bundle-plugins.ts:366
    Hook invocation awaits complete plugin discovery before evaluating any imported hook. The new discovery error can therefore prevent a PreToolUse policy hook in another plugin from returning its decision; the final tool outcome needs explicit mixed-plugin verification.
    Confidence: 0.87

What I checked:

  • Introduced limit: The pinned PR adds the shared 50-file budget and throws when a directory exceeds it. (src/bundle-plugins.ts:304, 22a241dc4ce0)
  • Error propagation: Inspection awaits hook discovery; listing awaits every plugin's inspection; hook invocation awaits the whole listing before running a hook. (src/bundle-plugins.ts:734, 22a241dc4ce0)
  • Regeneration impact: Native-tool regeneration awaits the same plugin listing, so an already installed oversized plugin can prevent regeneration. (src/native-tools.ts:611, 22a241dc4ce0)
  • Current main and release: Current main still uses the uncapped directory walk, and the available v0.1.0 release has no hook-walk limit. The PR remains necessary. (src/bundle-plugins.ts:345, 1a81d46cc5d3)
  • Contributor behavior proof: The captured PR body reports a compiled CLI run: 51 files and depth nine exit with limit errors, while 50 files and depth eight list successfully. The reviewer did not rerun it. (22a241dc4ce0)
  • Prior review continuity: The prior completed review identified the same upgrade blocker at the same head SHA. Contributor comments say the shared-budget and unique-file findings were fixed, while the strict-default decision remains open. (22a241dc4ce0)

Likely related people:

  • Dallin Romney: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
  • Vincent Koc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
  • Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

  • Implement the approved upgrade contract and verify fresh installs, existing oversized installations, and mixed-plugin hook decisions.
  • Resolve the merge conflicts and rerun npm run check and npm run pack:check on the resulting branch.

Rating scale

Score Internal tier Crab rank Meaning
6/6 S 🦀 challenger crab Exceptional readiness
5/6 A 🦞 diamond lobster Very strong readiness
4/6 B 🐚 platinum hermit Good normal PR; ordinary maintainer review
3/6 C 🦐 gold shrimp Useful, but confidence is limited
2/6 D 🦪 silver shellfish Proof or implementation needs work
1/6 F 🧂 unranked krab Not merge-ready
N/A NA 🌊 off-meta tidepool Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (11 earlier review cycles; latest 8 shown)
  • reviewed 2026-08-30T20:14:23.687Z sha 80cfe65 :: found issues before merge. :: [P1] Enforce the JSON cap across every declared hook path | [P1] Stream directory entries before applying the file limit | [P1] Keep upgrades compatible with existing hook trees
  • reviewed 2026-08-30T20:46:57.856Z sha 80cfe65 :: found issues before merge. :: [P1] Share the JSON-file budget across declared hook paths | [P1] Apply the file budget before materializing directory entries | [P1] Preserve existing plugin behavior before rejecting oversized trees
  • reviewed 2026-09-01T03:12:43.590Z sha 80cfe65 :: found issues before merge. :: [P1] Share the JSON-file budget across declared hook paths | [P1] Stop materializing wide hook directories before applying the cap | [P1] Settle upgrade behavior before rejecting existing hook trees
  • reviewed 2026-09-02T15:10:57.536Z sha 80cfe65 :: found issues before merge. :: [P1] Share the file cap across hook paths | [P1] Apply the cap before materializing directory entries | [P1] Settle upgrade behavior for existing hook trees
  • reviewed 2026-09-03T11:57:32.814Z sha 80cfe65 :: blocked before merge. :: [P1] Share the file budget across declared hook paths | [P1] Stream directory entries before applying the file limit | [P1] Avoid breaking existing hook trees without an approved transition
  • reviewed 2026-09-04T01:57:19.256Z sha 80cfe65 :: blocked before merge. :: [P1] Share the file cap across declared hook paths | [P1] Stream entries before enforcing the file limit | [P1] Settle the oversized-tree upgrade contract
  • reviewed 2026-09-16T16:56:21.244Z sha ebf6839 :: blocked before merge. :: [P1] Charge the shared budget only for unique hook files | [P1] Preserve upgrades until strict rejection has an approved transition
  • reviewed 2026-09-18T12:28:27.529Z sha 22a241d :: blocked before merge. :: [P1] Preserve upgrades until strict rejection has an approved transition

@clawsweeper clawsweeper Bot added merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Aug 30, 2026
readHooks now spends one 50-file budget across every declared hook
path. hookFiles walks with opendir so a wide non-JSON directory is
not loaded as one array before the cap is checked.

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
@SebTardif

Copy link
Copy Markdown
Contributor Author

Pushed ebf6839 for the two named code P1s:

  • One 50-file budget is now shared across every declared hook path.
  • Directory walks use opendir so a wide non-JSON directory is not loaded as one array before the cap is checked.

The oversized-tree upgrade contract (fail now vs opt-in) is still a maintainer product call. I did not change that default.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

Share the seen-file set with directory discovery so conventional
hooks/hooks.json plus a declared hooks directory counts as one file.

Signed-off-by: Sebastien Tardif <sebtardif@ncf.ca>
@SebTardif

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

Charge the shared budget only for unique hook files

Discovery now shares the seen-file set, so conventional hooks/hooks.json plus a declared hooks directory counts once. The oversized-tree upgrade contract is still a maintainer product call; I did not change that default.

@clawsweeper

clawsweeper Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

@clawsweeper clawsweeper Bot added merge-risk: 🚨 security-boundary 🚨 Merging this PR could weaken sandboxing, authorization, credentials, or sensitive data. and removed merge-risk: 🚨 availability 🚨 Merging this PR could cause crashes, hangs, restart loops, stalls, or process outages. labels Sep 18, 2026
steipete added a commit to SebTardif/babelfish that referenced this pull request Sep 30, 2026
Combine the hook tree and stdin limits from openclaw#23 and openclaw#24. Preserve exact boundaries and overlapping-path accounting, and keep existing early-exit tests within the new payload budget.

Co-authored-by: Sebastien Tardif <sebtardif@ncf.ca>
steipete pushed a commit that referenced this pull request Sep 30, 2026
Combine #23 and #24: cap hook discovery at 50 unique files and eight nested directories, and reject command-hook stdin above 1 MiB before spawning. Oversized decision events fail closed. Includes exact-boundary and overlapping-path regressions, preserved early-stdin-close coverage, compatibility documentation, and release notes.

Co-authored-by: Sebastien Tardif <sebtardif@ncf.ca>
@steipete

Copy link
Copy Markdown
Contributor

Thanks @SebTardif. The hook discovery fix is now merged in #24 together with the related stdin limit, with your co-author credit and changelog acknowledgment preserved. The 51-file regression fails on the previous code; exact 50-file/eight-directory boundaries and overlapping-path accounting pass with the fix. The combined candidate passed all 134 tests and package validation, and #24's exact-head cross-platform, CodeQL, and constrained-memory checks are green: https://github.com/openclaw/babelfish/actions/runs/36669279416. Closing this PR as incorporated.

@steipete steipete closed this Sep 30, 2026
@SebTardif
SebTardif deleted the fix/f005-hook-walk-cap branch September 30, 2026 17:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. merge-risk: 🚨 security-boundary 🚨 Merging this PR could weaken sandboxing, authorization, credentials, or sensitive data. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants